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
dist/docs/v2/{variant}/**/section.md        # Section bundles (where enabled)

How page.md files 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 page.md alongside each index.html.
3. fix_internal_links_post_processing() converts all internal links in page.md files to point to other page.md files using relative paths.
4. build_llm_docs.py then enhances subpage listings with H2/H3 headings, generates section bundles, converts all relative links to absolute URLs, and creates the llms.txt and llms-full.txt index files.

Enabling section bundles

To produce a section.md bundle for a documentation section:

1. Add llm_readable_bundle: true to the frontmatter of the section’s _index.md:

   ---
   title: Configure tasks
   weight: 8
   variants: +flyte +union
   llm_readable_bundle: true
   ---

That is all that is required. The bundle is generated at build time and listed in llms.txt, which is how agents discover it.

The LLM-optimized files are not surfaced as links on the pages they cover. They exist in the build and are reached through llms.txt, so there is nothing to add to the page body.

The llms-full.txt link conversion

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

• Cross-page: [Resources](../resources/page.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.