For a docs site, put the quickstart first, API reference second and the changelog third. Follow with guides, and put anything an assistant can skip in a final Optional section. Every entry is a Markdown link to a Markdown version of the page, followed by a one-line description. The file stays small, and the detail lives behind the links.
This article covers the fixed structure the spec requires, the section order that works for documentation, how to handle versioned docs, and a complete example you can adapt.
The structure is fixed; the sections are yours
The spec sets the order of the file: an optional BOM, an H1 with the project or site name, a short blockquote summary, optional prose, then zero or more H2 sections containing file lists [1]. You can't reorder those parts. What you control is which H2 sections exist, what order they come in, and which links go in each.
Each list entry needs a Markdown hyperlink. It may add a colon and notes about the file [1]. That "notes" slot is where your one-line descriptions go.
Section order for a docs site
The spec doesn't dictate section names or order. The order below is our recommendation, based on the questions people ask an assistant about a product.
| Order | Section | Why it goes here |
|---|---|---|
| 1 | Quickstart | Answers "how do I get started" and "how do I install it." Highest-value page for most questions. |
| 2 | Reference | API, CLI, config and error codes. Where exact names, parameters and limits live. |
| 3 | Changelog | Lets an assistant check whether an answer is current. |
| 4 | Guides | Task-based and conceptual pages: auth, webhooks, migrations. |
| 5 | Versions | Pointers to other doc versions, if you have them. |
| 6 | Optional | Secondary material: blog posts, tutorials, community pages. |
Keep each section short. A section with 40 links is a sitemap, and a sitemap already exists. Link the pages that answer the most questions, and let those pages link onward.
Quickstart
Link one or two pages: install, authenticate, first successful request. If your quickstart is split by language, link each variant and name the language in the description.
Reference
Link the index page for each reference area, not every endpoint. If your API reference is one large page, link that page. If you publish an OpenAPI file, link it and say so in the description.
Changelog
Link the changelog and any upgrade or migration guide. Descriptions should say what the page covers and how far back it goes, for example "Release notes for every version since 1.0."
Optional
The v2 spec notes that the Optional section no longer has mechanical semantics for context expansion. It remains a useful convention for secondary links that an agent can skip when context is tight [4]. Use it for that purpose and nothing more.
Link to Markdown, not rendered HTML
The proposal says links should point to LLM-friendly content, especially Markdown versions of pages [1]. Version 2 accepts both common URL patterns: appending .md to the full page URL (page.html.md) or replacing the extension with .md (page.md) [4]. Pick one and use it for every entry.
If your docs are built from Markdown or MDX, you already have the source. Publish it at predictable URLs. Serve it as text/markdown; charset=utf-8; Vercel's example does this, and returns /llms.txt itself as text/plain; charset=utf-8 [3].
The spec also recommends discovery links so a Markdown version can be found from the page itself. A page's Markdown version is advertised with rel="alternate" and type="text/markdown", and the llms.txt file with rel="describedby". Either an HTML link element or an HTTP Link header can carry them [1].
Versioned docs
The spec doesn't define a versioning scheme. It does define scope: a file can live at the site root or any subpath, it covers the URLs under its own path, and when more than one file applies, agents should use the most specific one [1]. You can build a versioning approach on that.
| File | Covers | Contents |
|---|---|---|
/llms.txt | Whole site | Latest stable version only, plus a Versions section |
/docs/v2/llms.txt | Pages under /docs/v2/ | Quickstart, reference and changelog for v2 |
/docs/v1/llms.txt | Pages under /docs/v1/ | Same structure for v1 |
Rules that keep this from going wrong:
- The root file should link only to the current version's pages. Mixing versions in one list is how an assistant ends up quoting a deprecated parameter.
- Name the version in each description when it isn't obvious from the URL.
- Keep the same section names in every file, so the structure is predictable.
- When you release a new version, update the root file in the same release step as the docs.
- Link older versions from a Versions section, not from Quickstart or Reference.
We can't say how any particular assistant resolves multiple files in practice. The spec's most-specific-file rule is the documented behavior, and the table above relies on it.
Worked example
This is a complete file for a fictional product, Acme. The first line is the H1 with the product name: # Acme API Docs. Directly below it, the file continues:
> Acme is a payments API. These docs cover the REST API (v2), client libraries for Python and Node, webhooks, and release history. Links point to Markdown versions of each page.
This file covers v2, the current version. Older versions are listed under Versions.
## Quickstart
- [Install and authenticate](https://docs.acme.example/v2/quickstart.md): Install the Python or Node library, create an API key, make a first request.
- [Send your first payment](https://docs.acme.example/v2/first-payment.md): End-to-end test-mode payment in under ten calls.
## Reference
- [REST API reference](https://docs.acme.example/v2/api.md): Every endpoint, parameter, response field and error code.
- [OpenAPI specification](https://docs.acme.example/v2/openapi.yaml): Machine-readable API definition for v2.
- [Webhook events](https://docs.acme.example/v2/webhook-events.md): Event types, payload shapes and retry behavior.
- [Rate limits and errors](https://docs.acme.example/v2/limits.md): Request limits per plan and how to handle 429 responses.
## Changelog
- [Release notes](https://docs.acme.example/changelog.md): Dated release notes for every version since 1.0.
- [Migrating from v1 to v2](https://docs.acme.example/v2/migrate.md): Breaking changes and renamed fields, with before and after examples.
## Guides
- [Authentication](https://docs.acme.example/v2/auth.md): API keys, OAuth, and key rotation.
- [Handling webhooks](https://docs.acme.example/v2/webhooks.md): Verifying signatures and processing events idempotently.
- [Testing](https://docs.acme.example/v2/testing.md): Test mode, test card numbers and sandbox limits.
## Versions
- [v1 docs](https://docs.acme.example/v1/llms.txt): Legacy API, maintained for security fixes only.
## Optional
- [Engineering blog](https://docs.acme.example/blog.md): Design notes and postmortems.
- [Community examples](https://docs.acme.example/examples.md): Third-party sample projects.
What makes the descriptions work:
- Each says what is on the page, not how good it is. "Every endpoint, parameter, response field and error code" beats "Comprehensive API reference."
- Each is one line. If you need two sentences, the page is probably two pages.
- Version-specific facts (v1, v2, "since 1.0") sit in the description, where an assistant reads them next to the link.
llms-full.txt is a separate decision
Vercel's example describes llms.txt as the project name, a summary and links, and adds a separate llms-full.txt for complete API documentation in one response [3]. That is a different file with a different job. See llms-full.txt vs llms.txt: what the spec says before deciding whether to publish one. Start with the index file.
Drafting and checking
Writing the first version by hand takes about an hour for a typical docs site. The free llms.txt generator drafts a spec-shaped file from a live homepage and sitemap, and you then reorder and rewrite descriptions as above. For a general walkthrough of the format, see how to write an llms.txt file. For background on what the file is for, see what is llms.txt.
Before publishing, check each of these:
- The first line is a single H1, and a blockquote summary follows it.
- Every link resolves with a 200 status and returns Markdown, not an HTML shell.
- Every link uses the same Markdown URL pattern.
- No section mixes versions.
curl -I https://yourdomain.com/llms.txtreturns 200 and a text content type.
What we don't know
Anthropic's engineering guidance points readers to official documentation sites that publish flat llms.txt files as a useful source of LLM-friendly docs [2]. The sources we reviewed don't say which assistants fetch the file automatically, how often, or whether it changes what they cite. Treat llms.txt as a low-cost way to give a clean path to your docs, not as a guaranteed lever.
What to do next
- List your quickstart, reference index and changelog URLs, and confirm each has a Markdown version.
- Write the H1, the blockquote summary and the three priority sections in that order.
- Add Guides, then Versions if you have them, then Optional.
- If you keep multiple doc versions, add a subpath file for each and keep the root file on the current version.
- Put the file at
/llms.txtand re-check it on every release.