Your llms.txt guide is out of date: what v2 changed

TL;DR: llms.txt v2 landed on 10 August 2026, and two of the things the guides taught you about the format are no longer true.

The spec moved and nobody said anything

So you added an llms.txt at some point, most likely from a guide, and it's been sitting at the root of your site ever since doing whatever it is that it does. llmstxt.org now reads "The /llms.txt file, v2" and carries a modified date of 10 August 2026. The whole v1 to v2 diff lives on a separate changes page, which the spec links exactly once, in a single sentence in the Background, and that's the only pointer to it you're going to get.

Which means every guide written before that date describes v1 as current, because it was. That's not a criticism of the guides. The problem is the shape of this particular topic: you write your llms.txt once, the article that told you how to write it keeps ranking, and nothing anywhere tells a reader that the ground moved under it.

I searched for how to write an llms.txt file while writing this, eleven days after v2 landed, and nothing on the first page of results mentions v2. Several of them carry 2026 in the title and were written this year. One from 6 May still tells you the Optional block is "reserved for lower-priority content the parser can safely skip when context windows are tight". That is the first of the two things that stopped being true.

Two things you were told that are no longer true

The Optional section does not mean what you think

v1 came with a tool called llms_txt2ctx that expanded an llms.txt file into a context for a model, and the Optional section was an instruction to that tool: these are the links you drop when the context has to be shorter. That's where "put your secondary links under Optional and agents will skip them" comes from. The tool is no longer part of the proposal, and the meaning left with it.

Verbatim from the changes page:

The context-expansion tooling is no longer part of the proposal, and with it
goes the special meaning of the Optional section, which told those tools
what to omit. Optional sections are still allowed, and remain a useful
convention for secondary links, but they no longer carry mechanical
semantics.

So if you structured your file around Optional because a guide told you agents skip it, they never did. The skipping was one local tool's behaviour and never a promise any agent made, and now it's not in the spec either. It's a name for a section, a useful one that the spec still recommends, but only a name.

In my opinion this is barely a loss and mostly a correction. A mechanical Optional was only ever real inside llms_txt2ctx, and I've never seen an agent read that heading and act on it, so v2 removing the semantics changes what your file means on paper and nothing about what happens to it in practice. The thing left over is worth saying out loud though: there is now no way at all to tell an agent "this part is skippable", and that was a genuinely useful thing to be able to say.

"Zero or more" means zero

v2's Format section lists the parts of the file, and the H2 file lists are "Zero or more markdown sections delimited by H2 headers". The H1 is the one thing that has to be there, and the spec says so directly: it is "the only required section". So a file that is an H1, a blockquote summary and a paragraph of context, with no H2 anywhere in it, is a conformant llms.txt.

Plenty of tooling reports that as a spec violation. Mine did. The validator I put up on 12 August, two days after v2 landed, flagged "No H2 sections" with its basis set to spec, and in the same run it told you the Optional section was reserved by the spec for secondary links. Both of those were wrong on the day they shipped, and both were fixed on the 16th. A file with no H2 sections is still a file an agent can do nothing with, so it's worth a warning, but the warning is about practice and not about the spec, and labelling it wrong is how you get people restructuring files that were fine.

What v2 actually adds

Link relations for discovery. This is the one the changes page says people asked for most. Given a page, how does a client find its markdown version, or the llms.txt that covers it, without guessing at URLs? v2 answers with standard relations:

Link: </docs/page.html.md>; rel="alternate"; type="text/markdown", </docs/llms.txt>; rel="describedby"

rel="alternate" type="text/markdown" points at a page's markdown version and rel="describedby" points at the llms.txt file that covers it. The clause worth reading twice is that these "can be provided as HTML <link> elements, or as an HTTP Link: response header. The header form also works for non-HTML resources, such as the markdown files themselves, and can be added in web server or CDN configuration without modifying any pages." So if you run a docs site behind a CDN you can ship the whole discovery half of v2 without touching a single page or redeploying anything.

Both markdown-twin URL forms are legal. v1 allowed only page.html.md, appending .md to the full page URL. v2 also allows page.md with the extension replaced, plus index.html.md or index.md for URLs without a filename. Publishing tools were already emitting the second form, and the spec blessed it rather than fighting it.

Subpath files finally mean something. v1 let you put an llms.txt at any path and said nothing about what that path implied. v2 does:

A file covers the URLs under its path, and where more than one file applies,
agents should use the most specific one.

That's also what lets you take part when you control a path and not the origin root. A GitHub Pages project site can never write into the host's /.well-known/, but it can put an llms.txt in its own directory and have that mean something.

Worth being precise about what that rule is and is not. It is not a search: an agent does not walk up the tree asking for files until one answers. Every file whose path is a prefix of the page's URL covers that page, and where several do, the longest path wins:

Mermaid source for the diagram

flowchart TB
    page["A page at<br>/workers/runtime-apis/"]
    other["A page at<br>/r2/buckets/"]
    root["/llms.txt<br>covers every URL on the host"]
    workers["/workers/llms.txt<br>covers /workers/ and below"]

    root -. "applies, but is less specific" .-&gt; page
    workers == "applies and is the most specific — an agent uses this one" ==&gt; page
    root == "the only file that applies" ==&gt; other

    classDef file fill:#dbe7fe,stroke:#2563eb,stroke-width:1px,color:#0f172a
    classDef url fill:#f2f5fa,stroke:#94a3b8,stroke-width:1px,color:#0f172a
    class root,workers file
    class page,other url

Both files genuinely cover /workers/runtime-apis/. The root one does not stop covering it because a deeper file exists — it is still the file that describes the rest of the host, and the deeper file wins only for the URLs beneath its own path.

Who actually does this

I checked these with curl on 21 August 2026:

Site	Root	Subpath
developers.cloudflare.com	200, 15,906 bytes	/workers/llms.txt 200, 82,671 bytes
docs.stripe.com	200, 89,857 bytes	—
docs.astro.build	404	—

Cloudflare is the one worth dwelling on. 15,906 bytes at the root and 82,671 bytes under /workers/ is the subpath rule doing its job in production: a small index for the whole developer site, and a big section-specific file for the part a coding agent is most likely to be deep inside already. Ask about Workers, get the Workers file, and the root file still covers everything the deeper one does not.

Here's what that pair looks like from the inside, checked from the page itself:

The note tagged spec is the v2 rule stated back at you: the file at /workers/ covers the URLs under /workers/, the root file covers everything, and an agent standing on this page takes the more specific one. Which file wins is a question you can only ask from a page, because the answer depends on which page you are standing on.

One curiosity while you're in there: llmstxt.org serves its own /llms.txt as text/plain. The spec says nothing about content types so nothing is broken, but if your checker treats anything other than text/markdown as a failure, it's going to fail the spec's own file.

Astro removed theirs

Astro deleted its files in withastro/docs#13538, titled "[i18nIgnore] Remove llms.txt files", merged on 20 April 2026. llms-full.txt and llms-small.txt went, and docs.astro.build/llms.txt is a 404 today as well. The stated reason is the one that should worry you if you maintain a docs site:

we've seen little uptake recently in usage — these files get very little traffic

They chose to put the effort into their MCP server instead, "and perhaps in the future offer per-page Markdown content", then signed off with "AI trends move quickly". The PR also shows what the files were costing them, flagged as "anecdotal obviously": two Netlify builds, 5m 6s with the files and 4m 22s without.

Two dates matter here. The removal is April and v2 is August, so what Astro measured was v1, and v1 gave an agent no way to find the file other than guessing the URL. Discovery is the exact hole v2 spends most of its new text filling. So I wouldn't read "very little traffic" as a verdict on the idea. I read it as a verdict on a file nobody could find.

That half-sentence about per-page Markdown aged strangely well. Astro walked out in April saying what they'd rather have is Markdown per page. Four months later the headline additions in v2 are markdown twins per page, plus the link relations that make them findable.

What v2 still doesn't do, and I'm not sure a text file at a well-known path ever can, is give an agent a reason to prefer your llms.txt over just fetching the page. Astro's answer to that was MCP, where the agent is handed the tool rather than having to go looking for a file, and that's a stronger position than a filename convention has ever been. Both things can be true: v2 is a real improvement, and the harder question is still open.

What to do about it

None of this takes long. If your file has an Optional section that you picked for mechanical reasons, keep the name if you like it but stop expecting it to do anything. If your pages have markdown twins, add the relations: one <link rel="describedby"> and one <link rel="alternate" type="text/markdown">, or the same thing as a Link: header at the CDN if you'd rather not go near the templates. serhiichuk.dev emits the describedby one on every page. And if your docs live under a path, an llms.txt at that path now has a defined meaning, so a large section-specific file sitting next to a small root one is a shape the spec understands rather than a shape you're getting away with.

What none of it buys you is search ranking. No engine has said it uses llms.txt for anything, and anyone who tells you otherwise is guessing.

I keep a checker for all of this at serhiichuk.dev/tools/llms-txt — it validates against v2 and labels every finding as spec, convention or hygiene, so you can decide which ones you care about. There's a Chrome extension as well, which runs the same rules against the tab you're on. That one exists because half of v2 is discovery, and the link relations live on the page rather than in the file — so a checker that only ever fetches a URL is looking in the wrong place for them. It also reaches what a hosted checker cannot: a staging host, an intranet address, anything that is not on the open internet.