Is llms.txt v2 a breaking change?

No. The required format is unchanged — the H1 with your site name, the blockquote summary, and the H2 file lists all work exactly as before. v2 clarifies and adds: it defines subpath files, allows two markdown URL forms instead of one, and adds standard link relations for discoverability. Existing valid files remain valid.

What does rel=describedby do in llms.txt?

It is a standard link relation that tells agents which llms.txt file covers a given page. You can add it as an HTML link element in a page's head or as an HTTP Link: response header. Agents that find a page can then locate the right llms.txt — and the markdown version — without guessing.

Should I use llms.txt at the root or in a subpath?

v2 says a file covers the URLs under its path, and where several apply, agents should use the most specific one. A root /llms.txt covers your whole site; /docs/llms.txt covers just the documentation. Use a subpath file when you only control a directory — for example a GitHub Pages project site — or when one section of the site needs its own curated list.

Spec update · August 2026 · AI readiness

llms.txt v2: What Changed in the 2026 Spec Update

Two years after the original proposal, the llmstxt.org specification has its first major revision. v2 (August 2026) adds discoverability, defines subpath files, and changes how agents are expected to use the file. Here is exactly what changed — and what you should update on your site.

Why a v2 at All?

The original llms.txt proposal was published by Jeremy Howard on September 3, 2024, when the idea that language models would routinely read websites was still speculative. By 2026 that is routine: thousands of sites publish an llms.txt file, documentation platforms such as Mintlify generate one automatically, Chrome's Lighthouse audits sites for one as part of its agentic browsing checks, and OpenAI, Anthropic, and Gemini all publish llms.txt files for their own developer docs. The revision (updated August 10, 2026) reflects what two years of adoption taught the community — and the most common request was discoverability.

Change 1: Two URL Forms for Markdown Versions

v1 specified one way to expose a machine-readable version of a page: append .md to the full URL, so page.html becomes page.html.md. In practice, many publishing tools replace the extension instead. v2 blesses both forms:

Appended: https://example.com/docs/page.html.md
Replaced: https://example.com/docs/page.md

For URLs without a filename, append index.html.md or index.md. Agents that follow a link from your llms.txt to a markdown page should now accept either form.

Change 2: Subpath Files Are Officially Defined

v1 allowed llms.txt in subpaths without saying what that meant. v2 defines it: a file covers the pages under its path, and where more than one file applies, agents should use the most specific one. A root /llms.txt covers the whole site; /docs/llms.txt covers only the documentation.

This matters for sites that control just a directory — a GitHub Pages project site, for example, can publish llms.txt in its own path even though it can never touch the host root. The FastHTML project does exactly this, placing its file at /docs/llms.txt to cover only its documentation pages.

Change 3: Standard Link Relations for Discoverability

Given a page, how does an agent find its markdown version — or the llms.txt file that covers it — without guessing? v2 answers with two standard link relations:

rel="alternate" type="text/markdown" — points to the page's markdown version
rel="describedby" — points to the llms.txt file that covers the page

You can provide them as HTML link elements in the page head:

<link rel="alternate" type="text/markdown" href="https://example.com/docs/page.md">
<link rel="describedby" href="https://example.com/docs/llms.txt">

Or as an HTTP Link: response header, which also works for non-HTML resources and can be added in web server or CDN configuration without touching any pages:

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

Change 4: Agents View, Then Follow Links

v1 described a tool, llms_txt2ctx, that expanded a file into an LLM context, and the Optional section carried special meaning for it. v2 drops the context-expansion tooling from the proposal and states the expectation directly: agents view or search the llms.txt to find what they need, then follow the relevant links — which should point to LLM-friendly content such as the markdown versions above.

The Optional section is still allowed and remains a useful convention for secondary links an agent can skip, but it no longer has mechanical semantics. The practical takeaway: keep the file small enough to fit in context, and put the detail behind the links.

What Did Not Change

The core format is untouched: an optional byte-order mark, the H1 with your site name (the only required element), a blockquote summary, optional context paragraphs, and H2 sections with markdown file lists. Root placement still works. Everything you learned from the format guide and best practices remains valid — existing files don't break.

Your v2 Update Checklist

Publish markdown versions of your key pages (either .md or .html.md form).
Point the links in your llms.txt at the markdown versions, not the HTML pages.
Add rel="alternate" and rel="describedby" via HTML link elements or an HTTP Link: header — see the Cloudflare Pages guide for CDN-level headers.
Use a subpath file such as /docs/llms.txt when you control only a directory.
Keep secondary links in an Optional section; keep the file under a few dozen links.
Re-validate after every change with the free validator.

The v2 update is small but meaningful: it makes llms.txt easier for agents to find, easier to consume, and usable by sites that only control a path. Generate a spec-compliant file with the generator, check it with the validator, and you're ready for the agentic web.