Markdown twin
The same page served as Markdown at the same address plus .md. Agents read it far better than a rendered site, and almost nobody publishes one.
A Markdown twin is the same page served as plain Markdown at the same address plus .md. A page at /docs/quickstart also answers at /docs/quickstart.md, with the same content in Markdown source.
Why it helps
A rendered documentation page is mostly not the documentation. It is navigation, a search box, a theme switcher, a cookie banner, a footer, and some scripts, wrapped around the part that matters.
An agent fetching that page has to find the content inside the noise. If the page renders its content with JavaScript, a plain fetch returns an application shell and nothing else.
A Markdown twin removes all of that. Headings are headings, tables are tables, code blocks are code blocks, and the whole thing is smaller, which matters when context is finite.
It is not cloaking
Worth being precise, because the two get confused.
| Cloaking | Markdown twin | |
|---|---|---|
| What is served | Different content to crawlers and people | The same content in a second format |
| Who can reach it | Only the crawler | Anyone, at a predictable address |
| Substance | Differs on purpose | Identical |
| Status | A manual penalty | A normal content negotiation pattern |
The rule that keeps it safe is simple: the twin must be the same content. If you start adding things to the Markdown that are not on the page, you have built a cloak.
How to publish one
Generate it from the same source as the HTML, in the same build. A hand-maintained twin goes stale, and a stale twin is worse than none because it will be believed.
Make it discoverable three ways:
<link rel="alternate" type="text/markdown" href="/docs/quickstart.md" />List the convention in llms.txt:
Every documentation page is also available as Markdown: add `.md` to the address.And say it on the page, so a human reader knows too.
Serve it correctly
- Content type
text/markdown; charset=utf-8. - A
200, not a redirect chain. - Not as a download. It should render as text in a browser.
- Include the canonical URL of the HTML page at the top, so a reader of the Markdown knows where it came from.
Worth pairing with a header
Put the source address, the publication date and the publisher at the top of the twin:
# Quickstart
> Install and send a first job in five minutes.
Source: https://acme.dev/docs/quickstart
Updated: 2026-09-03
Publisher: Acme, Inc.An agent quoting the page then has the attribution in front of it, which makes a correct citation more likely.
Common questions
What is a Markdown twin?
The same page served as plain Markdown at the same address plus .md. For example a page at /docs/quickstart also answers at /docs/quickstart.md with the same content as Markdown source.
Why publish a Markdown twin?
Agents read Markdown far better than a rendered documentation site. The HTML version carries navigation, scripts, cookie banners and layout, and if the content needs JavaScript to appear, a plain fetch returns nothing useful.
Is a Markdown twin cloaking?
No. Cloaking is showing different content to crawlers than to people. A Markdown twin is the same content in a second format, both public, both reachable by anyone. Keeping them identical in substance is what makes it safe.
How do you make a Markdown twin discoverable?
Link it from the HTML page with a link rel alternate tag pointing at the .md address, list it in llms.txt, and mention the convention on the page so a reader knows it exists.
Where this comes from
Armature ran 5,292 judged sessions with Claude Code, Codex and Cursor inside 51 realistic codebases, and published every run. The numbers on this page come from that work.