# llms.txt v2: what changed

> The llms.txt proposal was revised in August 2026. Four things changed: link relations for discoverability, both .md URL forms, subpath files, and the removal of context-expansion tooling. Here's what to do about each.

The [llms.txt proposal](https://llmstxt.org/) was revised in August 2026, nearly two years after the original. The file format itself did not change — a v1 file is still a valid v2 file. What changed is everything *around* the file: how agents find it, and what tooling the spec expects.

## The format is unchanged

The required structure is exactly as before: 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 H2 sections holding Markdown link lists. If your file scored 100 against v1, it still scores 100.

## 1. Link relations, so agents stop guessing

This is the substantial addition, and it answers the most common request 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"` — points at the llms.txt that covers this page.

  - `rel="alternate" type="text/markdown"` — points at this page's Markdown version.

Either can be an HTML `<link>` 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 such as the Markdown files themselves, and can be set in your web server or CDN config without touching a single page:

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

If you previously followed advice to advertise the file with `rel="alternate" type="text/plain"` — including earlier versions of our own guides — swap it for `rel="describedby"`. That was a reasonable convention before the spec had one; now it has one.

## 2. Both .md URL forms are now allowed

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

Nothing to migrate here — whichever form you already emit is now correct.

## 3. Subpath files are properly defined

v1 permitted an llms.txt outside the root but never said what it meant. v2 defines it: **a file covers the pages under its path, and where more than one applies, agents use the most specific**. So `/docs/llms.txt` covers everything under `/docs/`, and an agent reading a docs page prefers it over the root file.

This matters for anyone who controls a path but not a host — a GitHub Pages project site, a docs section on a shared domain — and it's the reason the spec sticks with a conventional filename instead of `/.well-known/`, which only ever exists at the origin root.

Practical consequence: if your documentation is the part agents care about, a `/docs/llms.txt` scoped to it is now a first-class choice, not a grey area.

## 4. Context-expansion tooling is out (and "Optional" lost its mechanics)

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 — so **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 no longer drive anything automatic.

Note that [llms-full.txt](/guide/llms-full-txt) was never part of the spec in either version. It's a widely adopted industry practice, and a good one for large documentation sets — just don't treat it as a requirement.

## What to actually do this week

  - Add `rel="describedby"` pointing at your llms.txt — one line in your layout, or one CDN header rule.

  - If you publish Markdown twins, advertise them with `rel="alternate" type="text/markdown"`.

  - Replace any `rel="alternate" type="text/plain"` discovery hint with `rel="describedby"`.

  - If your docs are the valuable part, consider scoping a `/docs/llms.txt` to them.

  - Re-run the [validator](/) — it now reports whether your pages advertise the v2 relations, and follows subpath files the way v2 says agents should.

## Why the revision happened 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 its assumptions were tested by real adoption.