llms.txt v2 is out — here's what actually changed

The llms.txt proposal was quietly revised in August 2026,
nearly two years after the original. If you already publish an llms.txt, the
good news is short: the file format didn't change. A v1 file is still a valid
v2 file. Nothing to migrate.

What changed is everything around the file — how agents find it, what a
subpath file means, and which tooling the spec expects. I maintain an llms.txt
validator, so I had to go through the diff line by line and change real code.
Here's the list, and what each item costs you.

The format is untouched

Still exactly this, in this order: an optional BOM, an # H1 with the project
name (still the only required element), a > blockquote summary, optional
heading-free prose, then zero or more ## sections holding Markdown link lists.

If your file scored well against v1, it scores the same against v2. You can stop
reading here if all you wanted was "do I need to rewrite my file". You don't.

1. Link relations — the actual new thing

This is the substantial addition, and it answers the most common complaint from
two years of adoption: given a page, how does an agent find its Markdown
version, or the llms.txt that covers it, without guessing at URLs?

v2 answers with two standard link relations:

• rel="describedby" → the llms.txt that covers this page
• rel="alternate" type="text/markdown" → this page's Markdown version

Either can be an HTML element:

<link rel="describedby" href="/llms.txt">
<link rel="alternate" type="text/markdown" href="/docs/page.html.md">

Or an HTTP response header — which is the only option for non-HTML resources
like the Markdown files themselves, and which you can set in your CDN config
without touching a single page:

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

If you followed the older advice — including advice I published myself — to
advertise the file with rel="alternate" type="text/plain", swap it for
rel="describedby". That was a reasonable convention while the spec had none.
Now it has one.

Cost to you: one line in your layout, or one CDN header rule.

2. Both .md URL forms are now legal

v1 specified one shape for a page's Markdown twin: .md appended to the full
page URL, so page.html → page.html.md. In practice several publishing tools
replaced the extension instead, producing page.md. v2 blesses both. For URLs
without a filename, append index.html.md or index.md.

Cost to you: zero. Whichever form you already emit is now correct.

3. Subpath files are finally defined

v1 permitted an llms.txt outside the root but never said what it meant. v2
defines it:

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

So /docs/llms.txt covers everything under /docs/, and an agent reading a docs
page prefers it over the root file.

This matters most if you control a path but not a host — a GitHub Pages project
site, a docs section on a shared domain. It's also the spec's stated reason for
sticking with a conventional filename instead of /.well-known/, which only ever
exists at the origin root.

This is the one that bit me. My validator normalized any input to
https://host/llms.txt — it threw the path away. So fastht.ml/docs came back
as "no llms.txt found" even though fastht.ml/docs/llms.txt has existed for two
years. That's the spec's own reference example, and I was reporting it as
missing. The fix is to target the path's file and walk up to the root only if
there's nothing there:

example.com/docs/tutorials  →  /docs/tutorials/llms.txt
                            →  /docs/llms.txt          ← found, stop
                            →  /llms.txt

One detail worth getting right: only walk up on a definitive 404/410. A 403
or 429 is a WAF blocking you, and a 5xx is a broken server — neither tells you
anything about the parent path, so treating them as "not here" invents a wrong
answer.

Cost to you: nothing, unless you build tooling. If you do, check your URL
normalization today.

4. The context-expansion tooling is gone (and ## Optional lost its teeth)

v1 described llms_txt2ctx, a tool that expanded an llms.txt into a single LLM
context. v2 drops it and states the expectation directly instead: agents view or
search the llms.txt, then follow the links they need. Which means the links
should point at LLM-friendly content, and the file itself stays small enough to
sit in context.

With that tooling goes the mechanical meaning of the ## Optional section, which
existed to tell those tools what to omit. Optional sections are still allowed and
still a useful convention for secondary links an agent can skip — they just don't
drive anything automatic any more.

Worth saying out loud since it comes up constantly: llms-full.txt was never
in the spec, in either version. It's a widely adopted industry practice, and a
good one for large documentation sets. Just don't call it a requirement.

What I'd actually do this week

1. Add rel="describedby" pointing at your llms.txt. One line.
2. If you publish Markdown twins, advertise them with rel="alternate" type="text/markdown".
3. Replace any rel="alternate" type="text/plain" discovery hint.
4. If your docs are the part agents care about, consider scoping a /docs/llms.txt to them — that's now a first-class choice, not a grey area.

Why there was a revision at all

Because the premise stopped being speculative. When llms.txt was proposed in
September 2024, "agents will read your website" was a prediction. Today
documentation platforms generate the file automatically, Chrome's Lighthouse
audits sites for one as part of its agentic-browsing checks, and the AI labs
publish llms.txt files for their own developer docs. v2 is what a proposal looks
like after real adoption tests its assumptions. The
changes page is short and worth reading in
full.

---

If you want to check where your own site stands against v2, my
llms.txt validator covers both halves of this
post. It follows subpath files the way v2 says agents should — paste
example.com/docs and it targets /docs/llms.txt, walking up to the root only
on a real 404 — and it reports which of the two link relations your pages
actually advertise, reading both the <link> tags and the Link: header, so a
CDN-level header counts the same as markup.

Comments

[Dmitry Sergeev]

Need to produce a short comment, casual, start with lowercase, specific reaction/question about this video. Maybe ask about key change or impact on SEO. Must not include quotes, no markdown, no URLs. Must be short one or two sentences. No em-dash. Use straight ASCII. No marketing. Let's craft: "so the new llms.txt adds that token limit tweak, does that mean we need to re‑index our sites?" Wait can't use em-dash; use hyphen. Use "re-index". Good.