LLM-optimized documentation

The build pipeline generates LLM-optimized versions of every page and several index files, designed for use by AI coding agents and AI search engines.

Output files

The make dist command (specifically the make llm-docs step) produces the following in each variant’s dist/docs/v2/{variant}/ directory:

Discovery hierarchy

dist/docs/llms.txt                          # Root: lists versions
dist/docs/v2/llms.txt                       # Version: lists variants
dist/docs/v2/{variant}/llms.txt             # Variant: page index with headings
dist/docs/v2/{variant}/llms-full.txt        # Full consolidated doc
dist/docs/v2/{variant}/**/<page>.md         # Per-page Markdown, section landings index their children

How the page twins are generated

1. Hugo builds the site into dist/ and also outputs a Markdown format into tmp-md/.
2. process_shortcodes.py reads from tmp-md/, resolves all shortcodes (variants, code includes, tabs, notes, etc.), and writes the result as the page’s .md twin beside its rendered index.html.
3. fix_internal_links_post_processing() converts all internal links in the twins to point to other twins using relative paths.
4. build_llm_docs.py then enhances subpage listings with H2/H3 headings, converts all relative links to absolute URLs, and creates the llms.txt and llms-full.txt index files.

The llms-full.txt link conversion

In llms-full.txt, all internal twin links are converted to hierarchical bold references:

• Cross-page: [Resources](../resources.md) becomes **Configure tasks > Resources**
• Same-page anchor: [Image building](#image-building) becomes **Container images > Image building**
• External links (http/https) are preserved unchanged.

This makes the file self-contained with no broken references.

Regenerating

LLM documentation is regenerated automatically as part of make dist. To regenerate only the LLM files without a full rebuild:

make llm-docs

New pages are included automatically if linked via ## Subpages in their parent’s Hugo output.