Serve a markdown version of key content
Ofrece una versión en markdown de tu contenido clave
Give agents a clean markdown representation of important pages through content negotiation or a "view as markdown" option, so they spend tokens on meaning, not page chrome.
Why
Equivalent markdown uses roughly 80% fewer tokens than HTML (Cloudflare analysis). The canonical AX framework (agentexperience.ax — Contextual Alignment) specifically calls out content negotiation for docs sites as a key AX practice. Biilmann documents real adoption: Stripe serves pure markdown doc pages, and Netlify measures guide quality by whether an agent can single-shot a feature using only the markdown version.
Do
Offer .md endpoints or HTTP content negotiation (Accept: text/markdown). Add a <link rel="alternate" type="text/markdown"> on HTML pages so agents can discover the markdown twin. For developer tools, also provide an AGENTS.md context file at the repo root.
Don't
Force agents to parse full HTML for core content. Don't serve the same payload to agents and humans — the optimal format for each is different.
Artifact
Return clean markdown when Accept: text/markdown:
GET /docs/quickstart HTTP/1.1
Accept: text/markdown
And/or advertise an alternate on the HTML page:
<link rel="alternate" type="text/markdown" href="/docs/quickstart.md">
Citations
- [01]Cloudflare AI Gateway — Token Efficiency Analysis ↗
Equivalent markdown uses roughly 80% fewer tokens than HTML, improving agent retrieval accuracy and reducing cost
- [02]agentexperience.ax — Principles of AX ↗
Contextual Alignment: use content negotiation for docs sites to make them respond with pure markdown when accessed from an agent
- [03]Mathias Biilmann — AX in Practice ↗
Stripe added 'copy to markdown for LLMs' and pure markdown versions of docs; Netlify added markdown button on Dev Hub guides; both reduce token waste for agents