Markdown for agents · Why serving markdown wins · mdream
[All guides](https://mdream.dev/guides/markdown-for-agents/guides)
Guide
# Markdown for agents
AI agents read markdown 2–5× more efficiently than HTML. Serve it via Accept-header negotiation, sitemap.md, and and every agent-originated request instantly becomes cheaper and smarter.
Updated 2026-04-22
## [The case for markdown](#the-case-for-markdown)
An agent fetching a modern web page gets 80–200 KB of HTML back. 90% of that is nav, footer, cookie banners, React serialized state, and inline styles. Even after Readability-style extraction, the overhead is real: every angle bracket is a token, and tokens are money.
Serving markdown cuts that to the content, nothing else. Typical savings on a documentation page: **70% fewer tokens, 80% less bandwidth**.
## [Three ways to serve markdown](#three-ways-to-serve-markdown)
### [1. Accept-header content negotiation](#_1-accept-header-content-negotiation)
The spec-correct approach. On `Accept: text/markdown`, respond with `Content-Type: text/markdown; charset=utf-8` and a `Vary: Accept` header.
```
GET /docs/getting-started HTTP/1.1
Accept: text/markdown, text/html;q=0.9
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept
```
[Test your site's content negotiation.](https://mdream.dev/guides/markdown-for-agents/tools/accept-header)
### [2. ``](#_2-link-relalternate)
For agents that don't advertise preferences (like OpenAI Codex CLI), publish the markdown URL in your HTML head:
```
```
Agents that parse HTML will follow the link and fetch the markdown version.
### [3. sitemap.md](#_3-sitemapmd)
A plain-markdown list of canonical URLs, analogous to sitemap.xml:
```
# Example Site
- [Home](/index.md)
- [Docs](/docs/index.md)
- [Getting Started](/docs/getting-started.md)
```
Place it at `/sitemap.md`. Agents crawling your site for RAG will prefer it over sitemap.xml.
## [Which agents respect markdown](#which-agents-respect-markdown)
| Agent | Sends `Accept: text/markdown`? | Follows `rel="alternate"`? |
| --- | --- | --- |
| Claude Code | yes | no |
| Cursor | yes | no |
| Codex CLI | no | yes |
| ChatGPT | no | partial |
| Perplexity | no | no |
| Gemini | no | no |
Expect this list to expand as markdown adoption becomes table stakes.
## [Implementation checklist](#implementation-checklist)
1. Generate an [llms.txt](https://mdream.dev/guides/markdown-for-agents/tools/llms-txt/generator) to give agents a structured map.
2. Add `` on every HTML page that has a markdown twin.
3. Implement Accept negotiation at the edge. Cloudflare Workers and Vercel Edge Functions both make this trivial.
4. Publish a sitemap.md.
5. [Audit](https://mdream.dev/guides/markdown-for-agents/tools/ai-audit) to confirm all four are in place.
## Check this on your site
[
Generative engine optimization (GEO) is the discipline of getting your content cited by ChatGPT, Claude, Perplexity, and Google AI Overviews. It blends classic SEO, structured data, and new formats like llms.txt + Accept-header markdown.](https://mdream.dev/guides/markdown-for-agents/guides/generative-engine-optimization) [
Answer engine optimization (AEO)
Answer engine optimization (AEO) is the practice of structuring content so that ChatGPT, Claude, Perplexity, Google AI Overviews, and voice assistants pick it as the canonical answer.](https://mdream.dev/guides/markdown-for-agents/guides/answer-engine-optimization) [