# 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. Source: https://armature.tech/library/markdown-twin Published: 2026-09-03 Publisher: Armature, Inc. (https://armature.tech) --- > 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: ```html ``` List the convention in `llms.txt`: ```md 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: ```md # 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. ## Read next - [Documentation for coding agents](https://armature.tech/library/documentation-for-coding-agents) (Markdown: https://armature.tech/library/documentation-for-coding-agents.md) - [llms.txt: what it is, what it does, and what to put in it](https://armature.tech/library/llms-txt-guide) (Markdown: https://armature.tech/library/llms-txt-guide.md) - [Audit your documentation for coding agents](https://armature.tech/library/audit-your-docs-for-coding-agents) (Markdown: https://armature.tech/library/audit-your-docs-for-coding-agents.md) - [Agent discoverability: the complete guide](https://armature.tech/library/agent-discoverability) (Markdown: https://armature.tech/library/agent-discoverability.md) --- Armature helps software products get discovered and used by coding agents. Service: https://armature.tech/discoverability · Results: https://armature.tech/leaderboards/sectors · Contact: contact@armature.tech