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 a markdown twin is

A markdown twin is a clean Markdown version of an HTML page, served at a parallel URL — typically the same path with a .md suffix (for example /guide and /guide.md). It contains the page's real content — headings, prose, lists, links — with none of the navigation, scripts, ads, or layout chrome that an agent would otherwise have to strip out of the HTML.

Why it matters for agents

HTML is built for browsers; Markdown is built for reading. When an agent fetches a full HTML page it spends tokens and parsing effort discarding wrappers before it reaches the substance, and it can misread content that depends on rendered layout. A markdown twin hands the agent exactly the content, in a format language models already consume natively — the lowest-Cost-of-Retrieval way to serve a page. It is a core artifact of the content dimension, the answer-first, machine-readable layer.

How to implement it

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

Generate Markdown from each page's source content (from your CMS, a build step, or an HTML-to-Markdown converter), keeping headings, links, and lists intact.
Serve it at a predictable twin URL — the canonical convention is appending .md to the HTML path — and link it via <link rel="alternate" type="text/markdown"> so agents can discover it.
Verify the twin: fetch /page.md, confirm it returns 200 as Markdown and its content matches the HTML page's substance.

This satisfies the audit check content.markdown_twin — pass criterion: a .md twin resolves 200 for sampled pages with content matching the HTML. Every page on this site has a .md twin as live proof. Pair this with content negotiation so the same URL can return Markdown on request, then verify the result with the Agent-Readiness Audit.

← Agent-Readiness · .md