# Markdown twin

A clean low-token markdown version of the page for agents.

**[Content](/docs/content)** · checked on every URL · 2 checks that can fail it

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** (L2)

Several independent organisations run it in production, though it is still niche on the open web. Direction of travel: ▲ rising, as of 2026-07-28.

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](https://www.mintlify.com/blog/context-for-agents) |
| Cloudflare (Markdown for Agents) | production | [explainx.ai](https://explainx.ai/blog/markdown-for-agents-content-negotiation-guide-2026) |
| Vercel (blog and changelog variants) | production | [vercel.com](https://vercel.com/kb/guide/make-your-documentation-readable-by-ai-agents) |
| GitBook, HackMD | production | [synscribe.com](https://www.synscribe.com/agentic-discovery/markdown-docs-for-ai-agents) |

## What we check

Absence is never a finding: every check below runs only once `markdownTwinPresent` is true, so a site that has not
adopted this is not assessed on it and appears in no report.

| Check | Kind | Raises | On whose authority |
|---|---|---|---|
| `markdownTwinWrongType` | medium severity | usability | specification.website / Dualmark profile |
| `markdownTwinEmptyHref` | medium severity | usability | specification.website / Dualmark profile |

## Examples

These are the fixtures the test suite runs through the real collector, not snippets written for a document.

- Correct: `test/e2e/test-pages/content/correct.html`
- Present but wrong: `test/e2e/test-pages/content/issues.html`

## Specifications

| Document | Revision | Kind |
|---|---|---|
| [specification.website — markdown source endpoints](https://specification.website/spec/agent-readiness/markdown-source-endpoints/) | living document | specification |
| [Dualmark — content negotiation](https://dualmark.dev/docs/spec/content-negotiation) | living document | specification |
| [Vercel: make your documentation readable by AI agents](https://vercel.com/kb/guide/make-your-documentation-readable-by-ai-agents) | living document | guidance |

Last re-read against the published documents: 2026-08-12.