How to Configure llms.txt v2: rel=alternate, describedby, and Markdown Discovery

If your site already publishes /llms.txt, the August 2026 v2 update is less about adding more text and more about fixing discovery. Previously, an agent that landed on an HTML page often had to guess whether a Markdown representation existed or whether the site exposed an llms.txt file. v2 adds explicit relationships for both cases.

Use rel="alternate" type="text/markdown" to point to a Markdown representation of the current page, and rel="describedby" to identify the llms.txt that applies to the page. These relationships solve a machine-discovery problem. They are not a shortcut to conventional search rankings.

What changed in v2

The official v2 change notes put discoverability first. A page can publish:

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

The same relationships can also be delivered through an HTTP Link header. The first tells an agent that a cleaner Markdown representation is available. The second points the agent to the llms.txt that describes the relevant site or documentation scope.

That is materially better than requiring every agent to guess whether /page/ maps to /page.md, /page.html.md, a content API or nothing at all.

How I would deploy it on a real site

Do not start by generating a Markdown mirror for every archive and tag page. Prioritize pages where a machine-readable representation has clear utility.

The first tier is developer documentation and tools: API references, MCP pages, agent documentation and tool instructions. Code, parameters and constraints survive more cleanly in Markdown than in a heavily styled application page.

The second tier is high-value tutorials and troubleshooting guides. Keep the HTML version optimized for people, but expose an equivalent Markdown representation for agents. The two versions should carry the same claims and constraints; the Markdown page must not become a separate keyword-stuffing surface.

The third tier is navigation and archive pages. Many of these do not need a dedicated Markdown copy at all. They simply need to lead agents toward the important content through ordinary links, sitemap coverage and a useful llms.txt file.

Verification checklist

Do not stop after seeing two <link> elements in source code. Verify the actual chain:

1. The HTML page returns 200 and has the intended canonical URL.
2. The rel=alternate Markdown URL returns 200 and matches the page’s meaning.
3. The rel=describedby target returns the expected llms.txt content rather than an HTML error page.
4. robots.txt and access controls do not contradict the machine-readable paths you just exposed.

For multilingual sites, verify that Markdown, canonical, hreflang and llms.txt scope stay language-consistent. A Chinese page that points an agent to an English-only machine representation can create a new discovery mismatch even if the HTML hreflang setup is correct.

What llms.txt is not

It is not robots.txt. robots.txt primarily governs crawler access and path rules; llms.txt is closer to a curated map and context layer for agents.

It is not sitemap.xml. A sitemap enumerates URLs for search systems, while llms.txt highlights context and useful machine-readable material.

And it is not a documented SEO ranking switch. The practical value of v2 is reducing guessing and making machine discovery explicit. That is useful on its own and does not require inventing a ranking promise. If the page also needs to expose structured actions after discovery, the next layer is WebMCP on Chrome 149; discovery and operation are separate concerns.

Check the whole readiness chain

The XBSTACK Agent Readiness Auditor treats llms.txt as one part of a broader chain: machine entry points, robots and sitemap health, content discovery, Markdown/llms.txt signals, and agent-operable capabilities should be evaluated separately.

A useful mental model is:

Agent discovers site
  -> discovers llms.txt
  -> discovers the target page
  -> optionally finds the Markdown representation
  -> understands page constraints
  -> uses WebMCP or MCP only when an actionable tool layer is actually present

That is why the two v2 link relations matter more than arguments about an ideal llms.txt word count. They turn part of agent discovery from convention and guessing into an explicit relationship controlled by the site.

Bottom line

If you already publish llms.txt, add rel=describedby where it helps agents locate the correct file. Where important documentation or tool pages have a stable Markdown representation, expose it with rel=alternate type="text/markdown". Then test the real HTTP responses and track whether the machine entry points are actually used.

If you do not yet have llms.txt, avoid generating a giant keyword directory just because “AI SEO” is fashionable. First make the site structure and important pages coherent, then use the Agent Readiness Auditor to identify the discovery gaps worth fixing.

Topic path / AI Agents

Continue from one agent pattern to the complete production system

The AI Agent hub organizes architecture, memory, tool use, evaluation, security, deployment and multi-agent coordination into a single learning path.

Open AI Agent hub → Review the architecture guide Subscribe