llms.txt v2 (August 2026): how to pass Lighthouse's llms.txt audit

TL;DR: llms.txt v2 (modified August 10, 2026) adds link-relation discovery for page-level markdown versions and blesses both .md URL forms; Lighthouse's agentic-browsing audit fails llms.txt only on a 5xx - a 404 is Not Applicable.

The first llms.txt proposal went up in September 2024 as a bet that agents would routinely read websites. Two years later the bet looks safe: thousands of sites ship the file, adoption across the top 1,000 SaaS sites keeps climbing, and Chrome 150's Lighthouse grades the file under a new experimental category. The llms.txt v2 specification, modified August 10, 2026, folds what adoption taught back into the spec, while Lighthouse's llms.txt audit enforces one narrow slice of it. Most coverage of both stops at "add a file to your root" - advice that can turn an audit-neutral site into a failing one, because the audit's failure mode is specific and backward.

What changed in llms.txt v2?

Four things, per the v2 changelog:

1. Link-relation discovery. Pages point agents at their markdown version with rel="alternate" type="text/markdown" and at the covering llms.txt with rel="describedby", either as HTML link elements or as an HTTP Link header. The header form also works for non-HTML resources and can be set in web server or CDN configuration without modifying pages.
2. Both .md URL forms blessed. v1 only specified appending .md to the full page URL (page.html.md); publishing tools in the wild replace the extension instead (page.md). v2 allows both. Extensionless URLs get index.html.md or index.md.
3. Subpath scope defined. An llms.txt at /docs/ covers the pages under /docs/, and where more than one file applies the most specific one wins. This is what lets a GitHub Pages project site, which controls a path but not the origin root, participate fully.
4. Consumption model stated, tooling dropped. v2 states the expectation directly: agents view or search the file, then follow links to LLM-friendly content. The llms_txt2ctx context-expansion tool is gone from the proposal, and with it the mechanical meaning of the Optional section - it survives as a convention for secondary links an agent can skip.

What does a v2-compliant llms.txt file look like?

The format is deliberately small. An optional byte-order mark, then an H1 with the project or site name (the only required section), then a blockquote summarizing the site, then any amount of plain markdown detail, then H2-delimited file lists where each entry is a markdown link with an optional one-line note:

# FastHTML

> FastHTML is a python library for creating server-rendered
> hypermedia applications.

Important notes:

- Not compatible with FastAPI syntax
- Compatible with vanilla JS, not React or Vue

## Docs

- [Quick start](https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md): A brief overview of many features

## Optional

- [Starlette subset](https://gist.githubusercontent.com/jph00/809e4a4808d4510be0e3dc9565e9cbd5/raw/starlette-sml.md): useful background

Underneath the file sit the page-level markdown versions v2 formalizes: the same content at the same URL with the extension swapped (page.md) or appended (page.html.md). Links inside llms.txt should point at those markdown files rather than HTML pages, because the detail lives behind the links and gets fetched only when an agent needs it.

How does Lighthouse's llms.txt audit score the file?

The audit lives in the Agentic Browsing category, which shipped with Chrome 150 in May 2026 and sits alongside three sibling groups: WebMCP integration, agent-centric accessibility, and layout stability. The category breaks with Lighthouse convention - there is no weighted 0-100 score, only a fractional ratio of agentic-readiness checks passed plus per-audit pass and fail statuses. Everything is deterministic, so the numbers reproduce in CI.

Inside the category, the llms.txt check is the entirety of the Discoverability group, and it does less than most people assume: it verifies the presence of a machine-readable summary at the domain root. That is the whole check. It does not parse your H2s, validate links, or grade file quality. A file with nothing but an H1 passes the same audit as a carefully curated one.

Keep the stakes in proportion: llms.txt helps an agent that has already decided to read your site find the right page faster. Whether the content gets cited still depends on the 13 signals AI assistants score once they arrive, and the category itself is experimental and not a Google ranking factor.

Why does your llms.txt audit fail when a missing file is fine?

The audit marks a page three ways, and the middle one surprises people. No file at all (404) is Not Applicable, because the file is optional. A file that serves correctly passes. A server error while retrieving llms.txt fails the audit outright.

That inversion creates a real trap. A site with no llms.txt is audit-neutral, and the common "fix" - routing /llms.txt through the application framework so it can be generated dynamically - is exactly what produces the 5xx that fails. SPA rewrites that send every unknown path to index.html, middleware that throws on unknown extensions, and WAF rules that challenge non-browser clients all convert a harmless 404 into a failing 500. Check before you build: curl -I https://example.com/llms.txt should return 200 with a text/markdown content type. If it returns 500 today, fixing the routing matters more than writing the file.

How do you make a site pass the audit today?

1. Curl -I your /llms.txt URL and confirm it returns 200, not a 5xx disguised by a rewrite rule.
2. Publish a v2-format file at the root: H1 name, blockquote summary, H2 file lists linking markdown versions.
3. Serve markdown versions of the pages agents need (page.md or page.html.md) and expose them with rel="alternate" type="text/markdown" via a Link header.
4. Add rel="describedby" pointing at the covering llms.txt in the same header.
5. Re-run Lighthouse in Chrome 150+ and confirm the llms.txt audit flips from fail to pass.

The Link header is the low-effort half of v2 discovery, because one nginx or CDN line covers every page on the site:

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

The audit only needs steps 1 and 2. Steps 3 and 4 are the v2 discovery layer that makes the file worth having beyond the checkmark. And keep the citation work in order: the file helps agents navigate, while on-page extraction signals like FAQPage schema still do the heavier lifting for whether an assistant quotes you.

FAQ

Does llms.txt affect Google rankings?

No. The Agentic Browsing category is experimental, reports a pass ratio instead of a quality score, and is not a ranking factor. Lighthouse grades the file for agent discoverability, not for SEO points.

What is the difference between llms.txt v1 and v2?

v2 adds link-relation discovery (rel="alternate" type="text/markdown" and rel="describedby"), allows both page.md and page.html.md URL forms, defines what a subpath llms.txt covers, and drops the llms_txt2ctx expansion tool along with the Optional section's mechanical meaning.

Why is my llms.txt audit failing instead of showing Not Applicable?

Because the URL returns a server error. Lighthouse fails the audit only when fetching /llms.txt errors out with a 5xx; a plain 404 would be Not Applicable since the file is optional. Fix the routing so the file serves 200, or remove it so the URL 404s again.

Do I need markdown versions of every page?

Not for the audit, which only checks the root file. v2 recommends markdown versions for pages agents actually need, discovered via the rel="alternate" type="text/markdown" relation, but nothing in the Lighthouse check reads them.

Does llms.txt replace robots.txt or sitemap.xml?

No. robots.txt states access policy, sitemap.xml lists indexable pages for search engines, and llms.txt is a curated on-demand overview for agents doing inference. The spec positions it as a complement to both.