Markdown twin
A clean low-token markdown version of the page for agents.
Why an agent cares
The same content in markdown costs an agent a fraction of the tokens and none of the layout noise. A twin that 404s, redirects to the HTML, or serves the wrong media type is worse than none, because the agent has already paid for the round trip.
Adoption
Early production. Several independent organisations run it in production, though it is still niche on the open web.
Direction of travel: ▲ rising, as at .
Docs platforms serve markdown by default and Cloudflare shipped edge HTML-to-markdown conversion, but only 3 of 7 major coding agents actually negotiate for it (Checkly, Feb 2026).
| Adopter | Depth | Evidence |
|---|---|---|
| Mintlify | default-on | mintlify.com |
| Cloudflare (Markdown for Agents) | production | explainx.ai |
| Vercel (blog and changelog variants) | production | vercel.com |
| GitBook, HackMD | production | synscribe.com |
What we check
markdownTwinPresent is true, so a site that has not adopted this is not assessed on it and appears in no report. 2 of these 2 can fail it. In a Lumar crawl these land on the page's own row.| Check | Severity | Raises | On whose authority |
|---|---|---|---|
markdownTwinWrongType | medium | usability | specification.website / Dualmark profile |
markdownTwinEmptyHref | medium | usability | specification.website / Dualmark profile |
Examples
Both of these are fixtures the test suite runs through the real collector, not snippets written for a document: the first is a shape we score as valid, the second is one we flag.
<!-- markdownTwinPresent + correct: alternate link, text/markdown, distinct .md URL.
(The .md body itself is a server fetch — validated by unit tests, not here.) -->
<link rel="alternate" type="text/markdown" href="https://example.com/content/correct.md" /><!-- markdownTwinPresent: yes (Markdown alternates are advertised). Each link below is present but
wrong, triggering one defect.
markdownTwinWrongType: a .md alternate declared as text/html, so agents won't recognise it. -->
<link rel="alternate" type="text/html" href="https://example.com/content/issues.md" />
<!-- markdownTwinEmptyHref: a text/markdown alternate with an empty href declares no twin.
(A self-referential href is NOT flagged here — it can be a valid content-negotiation twin; that
determination is a fetch-phase concern, see SOURCES.md.) -->
<link rel="alternate" type="text/markdown" href="" />Specifications
| Document | Revision | Kind |
|---|---|---|
| specification.website — markdown source endpoints | living | specification |
| Dualmark — content negotiation | living | specification |
| Vercel: make your documentation readable by AI agents | living | guidance |
Last re-read against the published documents: .