Serve Markdown Twins of Your Pages

Serve a .md copy of every HTML page so agents read your content without parsing layout markup — the lowest-Cost-of-Retrieval clean read.

What is a markdown twin?

A markdown twin is a clean Markdown version of an HTML page served at a parallel URL — usually the same path with a .md suffix (/guide and /guide.md). It carries the page's substance — headings, prose, lists, links — with none of the navigation, scripts, ads or layout chrome an agent would otherwise strip out. Its media type is text/markdown, registered by RFC 7763 with charset as a required parameter (IETF, 2016). The llms.txt proposal recommends the same .md convention for every page and lists Mintlify among the docs platforms that generate such twins for every site they host (llmstxt.org, 2026).

Why do markdown twins matter for agents?

Markdown twins matter because HTML is built for browsers and Markdown for reading: on 7 September 2026 the markdown response for this page reported, in its X-Bytes-Saved header, about 12 KB saved — 74 % smaller than the HTML twin, uncompressed — bytes an agent would otherwise spend discarding wrappers before reaching the substance. Every page on this site fetched with Accept: text/markdown reports its own saving in that header. A twin hands the agent exactly the content, in a format language models consume natively: the lowest-Cost-of-Retrieval way to serve a page and a core artifact of the content dimension.

How do you serve markdown twins?

Serve markdown twins by generating the Markdown, publishing it at a predictable URL, and confirming it mirrors the page.

1. Generate Markdown from each page's source content (CMS, build step or HTML-to-Markdown converter), keeping headings, links and lists intact.
2. Serve it at the HTML path plus .md with Content-Type: text/markdown; charset=utf-8, and advertise it with <link rel="alternate" type="text/markdown" href="/page.md"> — the HTML Standard defines alternate plus type as a reformulation of the document in that format (WHATWG, 2026).
3. Verify: fetch /page.md, confirm 200, the text/markdown type and content that matches the HTML page's substance.

The Agent-Readiness Audit's markdown-alternate check (5 of 100 points) looks for that link tag; its markdown-negotiation check (9 points) needs the canonical URL itself to answer Accept: text/markdown with Markdown. Every page on this site has a .md twin as live proof — this one at /agent-readiness/markdown-twins.md — and pairs it with content negotiation.

Markdown twins — frequently asked questions

Which content type should a markdown twin use?

text/markdown with an explicit charset, for example text/markdown; charset=utf-8. RFC 7763 registers the type and makes charset a required parameter (IETF, 2016); the twins on this site send exactly that header.

How does an agent discover a markdown twin?

Through the link element with rel alternate and type text/markdown in the HTML head, which the HTML Standard defines as a reformulation of the document in that format (WHATWG, 2026), or through the fixed convention of appending .md to the path, as llmstxt.org proposes.

How much smaller is a markdown twin than the HTML page?

On this site, 74 % for this page: on 7 September 2026 its markdown response reported about 12 KB saved in the X-Bytes-Saved header, uncompressed. Every page on this site fetched with Accept: text/markdown carries that header, so the figure is checkable on any page.

Related: the content dimension · content negotiation · the Frontier Model Matrix · audit your site

← Agent-Readiness · .md