How many sections should an llms.txt file have?

There is no number in the spec, and live files do not converge on one: of the 26 real files we fetched on October 28, 2026, the counts ranged from 1 to 2,300 with a median of 8.5. Twelve files sit between 4 and 14 sections, which is the band where a file stays scannable and still covers the whole site. Below that you are probably hiding pages; far above it the section list stops helping an agent choose what to read first.

Does the heading text of an llms.txt section matter?

Yes, because the heading is the only label an agent gets for a group of links before it reads them. Files that name sections after what a reader wants, such as When to use Vercel or Instructions for AI Agents, tell the model when to open the section. Files that name them after internal structure, such as Other or More pages, give nothing to decide with. Short labels are normal; 25 of 26 files average under three words per heading.

What is the Optional section in llms.txt?

The spec reserves the heading Optional for links a reader can skip if it needs a shorter context. Because the word is a marker rather than a description, its position carries the meaning: 7 of the 8 files that use it put it last. Nuxt places one entry after it, an MCP server link, which means the file's skip instruction and its final entry disagree.

Format & Spec · October 2026

llms.txt Section Headings

An llms.txt file is one H1, one summary line, and then a set of H2 sections holding links. The links get audited; the headings that group them usually do not. We fetched /llms.txt from 32 hosts on October 28, 2026 and parsed the heading structure of the 26 that returned a real file — section counts, naming, ordering, and where the reserved Optional marker lands.

What 26 Live Files Do With Their H2s

Fetched with a desktop user agent and Accept: text/plain, redirects followed, counted only when the body opened with an H1. Six candidates failed: docs.astro.build, www.11ty.dev, tailwindcss.com and docs.python.org return 404 (the first two with 100 KB and 134 KB of HTML behind the path), while docs.smith.langchain.com and www.heroku.com answer 200 with a body that does not start with a heading at all.

File	H2	H3	Links	Last section
ai-sdk.dev	2,300	1,954	6,148	Using tools
posthog.com	68	1	4,517	Optional
docs.convex.dev	33	0	411	team-management
docs.stripe.com	27	16	527	Optional
docs.railway.com	17	43	414	More pages
docs.github.com	14	0	117	More pages
www.checklyhq.com	11	5	68	Additional Resources
ui.shadcn.com	9	7	111	Registry
vercel.com	9	0	28	Optional
docs.anthropic.com	5	12	822	English
bun.sh	2	0	322	Optional
react.dev	2	10	180	API Reference
vite.dev	1	7	49	Table of Contents

Across the 26 files: 9,013 links, 286 sections, a median of 8.5 sections per file, and 22 of 26 opening with the blockquote summary the spec asks for.

One Heading or Two Thousand: The Real Distribution

The sorted section counts are 1, 1, 2, 2, 2, 2, 3, 3, 4, 4, 5, 8, 8, 9, 9, 9, 10, 11, 14, 14, 17, 20, 27, 33, 68, 2,300. Eight files use three sections or fewer and twelve sit between four and fourteen, so the practical band is narrow.

vite.dev has a single H2 called Table of Contents with 49 links under it and seven H3 groups doing the work the H2s would normally do. llmstxt.org has one section, Docs, and three links — right for a site that is a specification rather than a product.

ai-sdk.dev/llms.txt is the outlier that matters. It returns 4,958,807 bytes with 42 H1 headings, 2,300 H2s, 1,954 H3s and 6,148 links, and 1,116 of its sections contain no link at all — the shape of a documentation body served at the index path. Its /llms-full.txt is 4,952,143 bytes, so the two paths return effectively the same document. That is legitimate delivery, but it is not an index: an agent that wanted a map has to read the whole territory. If your build emits a full-context file, keep /llms.txt small and point at the bundle from an entry inside it — see llms.txt vs llms-full.txt.

Optional Is a Reserved Word, and Seven of Eight Files Put It Last

The spec defines Optional as the section for links a reader can skip when it needs a shorter context. Eight of the 26 files use it — Stripe, Nuxt, bun, Hono, Mintlify, Vercel, PostHog and Perplexity — and in seven of them it is the final H2. That is the whole convention: the position is the meaning.

Nuxt is the exception. Its order is When to use this, Documentation Sets, Nuxt v4 Documentation, Examples, Deployment Guides, Blog, Optional, MCP Server — a server entry sits after the skip marker, so a reader that honours the marker never sees it. Mintlify's file shows the discipline the other way round: Docs, Pages, Blog, Library, Customers, Legal, Security, Optional. Nothing valuable after the cut.

Catalog Words or Sentences: Two Naming Styles

25 of the 26 files average under three words per heading; headings are labels, not prose. What varies is what the label promises. Fourteen files name sections after document types — Docs, Documentation, Guides, Examples, API Reference, Blog, Changelog, Pricing — stable and easy to generate, but silent on whether a section is relevant to the task.

Five files lead with a sentence that does: When to use this (Nuxt), When to use Checkly, When to use Resend, When to use Vercel, When to use AI SDK. Five more put the reader's behaviour in a heading — Stripe's Instructions for Large Language Model Agents: Best Practices for integrating Stripe, GitHub's How to use, Vercel's How agents should use Vercel, Sentry's For AI Agents, Webflow's Instructions for AI Agents, PostHog's Instructions for AI Coding Assistants.

Those headings cost ten words and buy routing: an agent scanning the file can decide whether to open a section before spending the request. Stripe's eleven-word title is the longest in the sample and the only one close to a sentence; the working middle ground is a When to use section plus type-named sections underneath, which is what Nuxt and Vercel both do.

Lowercase Slugs, Empty Sections and H3 Nesting

Three details in the data are worth knowing before you copy somebody's file.

Headings that are URL paths. docs.convex.dev uses all 33 of its H2s as lowercase route segments — understanding, quickstart, functions, database, realtime, team-management. Only 2 of 26 files do this.
Sections with no links. Outside the ai-sdk bundle there are 14 such sections across seven files — four in Anthropic's file, four in Checkly's, two in Vercel's and one each in Svelte, Webflow, Sentry and MongoDB, and most of them are the headings that carry guidance instead of links. When the spec says a section holds a list of links, prose in an H2 is a weaker signal: an agent that walks H2 then links finds nothing. Put the guidance in the blockquote under the H1 and keep H2s for links.
H3 nesting. Eleven files use H3s, up to 43 in Railway's file and 16 in Stripe's. The spec documents only H1 and H2, so H3 behaviour is whatever each parser decides; it is readable and harmless, but it is not a contract. If a section has grown past roughly 30 links, splitting it into a second H2 is the safer shape than nesting.

A Heading Template and a Two-Minute Check

The shape that survives contact with the files above: one H1, one blockquote, then an intent section, then type-named sections ordered by how often a task needs them, then Optional last and nothing after it.

# Example Product

> One paragraph: what this site is, who it is for, what to read first.

- Key entry point: https://example.com/start.md

## When to use Example Product
- What it does: https://example.com/overview.md

## Documentation
- Install: https://example.com/install.md
- API reference: https://example.com/api.md

## Guides
- Migrating from v1: https://example.com/migrate.md

## Optional
- Changelog: https://example.com/changelog.md

Then check the headings you shipped. This reports the section list, the count, and any section with no link beneath it:

# 1. the headings, in order
curl -s https://example.com/llms.txt | grep '^## '

# 2. how many sections and links
curl -s https://example.com/llms.txt | grep -c '^## '
curl -s https://example.com/llms.txt | grep -oE '\]\([^)]+\)' | wc -l

# 3. is Optional the last heading?
curl -s https://example.com/llms.txt | grep '^## ' | tail -1

# 4. any heading that is not followed by a link
curl -s https://example.com/llms.txt | awk '/^## / { if (name != "" and links == 0) print "NO LINKS:", name; name = substr($0, 4); links = 0; next } /\]\(/ { links++ } END { if (name != "" and links == 0) print "NO LINKS:", name }'

Step 3 catches the most common mistake in the sample, and step 4 catches the second. If you would rather generate the skeleton than hand-write it, the llms.txt generator emits the H1, summary and section headings from your URL list, and the checker reports the section and link counts it parsed so you can compare them against your own page inventory. For the deeper structural rules — H1 format, summary length, escaping — see the llms.txt format, and for what goes inside the entries themselves, link descriptions.

Headings are the cheapest part of the file to change and the only part an agent reads before deciding what to fetch. Eight sections named after what a task needs will beat sixty named after your repository layout.