# Markdown versions of pages for AI agents > Why a site may serve Markdown versions of pages to AI agents and three ways to do it: a separate .md address, the Accept header and a rel=alternate link Page: https://llms-full-txt.ru/en/guides/markdown-pages/ Site index: https://llms-full-txt.ru/en/llms.txt A Markdown version is the same page without menus, footer, ads and styling: only headings, text, lists, tables and links. It is easier for an agent. An HTML page often carries less useful text than markup around it, and the amount a model can read at once is limited. It is an addition to HTML, not a replacement. People and search engines still get the ordinary page. ## HTML and Markdown of one page - What a client receives - HTML - for browsers and search - Menus, header, footer, scripts, styles - Structured data in the page code - A lot of service markup around the text - Markdown - for an agent - Content only - Headings and lists keep the structure - No JSON-LD and no interactive parts ## Three ways to serve Markdown **A separate address** `.md` is appended to the page address. The [second edition](https://llmstxt.org/) of the `llms.txt` proposal describes this. ```text https://example.com/docs/install.html the page https://example.com/docs/install.html.md its Markdown version https://example.com/docs/ a page without a file name https://example.com/docs/index.html.md its Markdown version ``` Both forms are allowed: `page.html.md` and `page.md`. The advantage: the address opens in a browser and can be listed in `llms.txt`. **The Accept header** One address, and the client picks the format. An agent asks for Markdown with a request header: ```http GET /docs/install/ HTTP/1.1 Host: example.com Accept: text/markdown ``` The server answers with the same content typed `text/markdown`. An ordinary browser does not send that header and gets HTML. The documentation of OpenAI, Stripe and Cursor works this way. Since February 2026 [Cloudflare](https://blog.cloudflare.com/markdown-for-agents/) can do the conversion on its side, with no changes to the site. **A rel=alternate link** The page itself says where its Markdown version is. This relation comes from the second edition of the proposal: ```html ``` The same can be sent as a response header: ```http Link: ; rel="alternate"; type="text/markdown" ``` The agent does not have to guess the address: it reads it from the page. The ways do not exclude one another. More on discovery relations: [Discovery of the file and Markdown versions](https://llms-full-txt.ru/en/specification/discovery/). ## What a Markdown version should contain - **The same content as the HTML.** Different text for machines is cloaking, and search engines treat it badly. - **One first-level heading** and meaningful section headings. - **Absolute links.** An agent reads the file outside the site and has nothing to resolve a relative path against. - **Tables as tables, code in code blocks.** A machine cannot read a screenshot of a table. - **No navigation, footer or forms.** - **Content type `text/markdown` or `text/plain`**, UTF-8. ## How it relates to llms.txt `llms.txt` should link to Markdown versions when they exist. Then an agent walks the whole path: the map, then clean text. Without Markdown versions, a file linking to ordinary pages is still valid. The proposal recommends Markdown and does not require it. ## What is known about the benefit **Confirmed** - The documentation sites of OpenAI, Anthropic, Stripe, Cloudflare and GitHub serve Markdown versions of pages. - Documentation platforms generate them automatically for every hosted site. - [Mintlify](https://www.mintlify.com/blog/the-state-of-knowledge-2026-highlights) reports that on its sites agents request documentation more often than people. The source has an interest: it is its product. **Not proven** - That a Markdown version increases citations or referrals. - That the bots of AI search systems request `.md` by themselves. In an [OtterlyAI](https://otterly.ai/blog/the-llms-txt-experiment) experiment there was not a single such request in 14 days. **What it does not mean** - It is not a way into a search index: search reads HTML. - It does not replace structured data: Markdown carries no entity markup. The sober conclusion: Markdown versions help where agents read a site while working, above all in documentation. For a store or a blog it is groundwork, not an urgent task. More in the blog: [Cloudflare serves Markdown to agents](https://llms-full-txt.ru/en/blog/cloudflare-markdown-for-agents/), [the Mintlify test of four formats](https://llms-full-txt.ru/en/blog/mintlify-markdown-benchmark/). ## How to check 1. Request the page with `Accept: text/markdown`, or open the address ending in `.md`. 2. The response is `200`, typed `text/markdown` or `text/plain`. 3. The body is text, not an HTML page. 4. The content matches the ordinary page. 5. Links are absolute and working. 6. When `rel="alternate"` is present, its address answers `200`. ```bash curl -sI -H 'Accept: text/markdown' https://example.com/docs/install/ curl -sI https://example.com/docs/install.html.md ``` ## Who does this - [OpenAI](https://developers.openai.com/llms.txt): A root index plus nested files for /api, /codex, /commerce. Does not prove: that chatgpt reads other sites’ llms.txt. - [Anthropic](https://platform.claude.com/llms.txt): A docs index and the full text in one file. Does not prove: that claude reads other sites’ llms.txt. - [Cloudflare](https://developers.cloudflare.com/llms.txt): A very large index: the full text takes 67 MB. Does not prove: that a file this big is usable by an agent as a whole. - [Stripe](https://docs.stripe.com/llms.txt): llms-full.txt is not required: an index and Markdown pages are enough. Does not prove: that skipping the full file is a general rule. - [Cursor](https://cursor.com/llms.txt): The only measured site with rel=describedby from the second edition. Does not prove: that the second edition is widely adopted. - [GitHub Docs](https://docs.github.com/llms.txt): An index without a full file on large docs. Does not prove: that copilot relies on this file. - [Mintlify](https://www.mintlify.com/docs/llms.txt): The platform generates the files automatically for every site it hosts. Does not prove: the quality of each generated file. - [Yandex Cloud](https://yandex.cloud/llms.txt): An example on a Russian site. Does not prove: that yandex search uses such files. Checked October 3, 2026.