# 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 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 discarding wrappers before reaching the substance, and 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.

## How to implement it

1. 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.
2. 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.
3. 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: a `.md` twin resolves 200 for sampled pages with matching content). 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.

Related: [the content dimension](/agent-readiness/content) · [content negotiation](/agent-readiness/content-negotiation) · [the Frontier Model Matrix](/models) · [audit your site](/services)