# AX-SYS-02: Serve a markdown version of key content

> Context and comprehension · intermediate · AX-SYS-02

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`:

```http
GET /docs/quickstart HTTP/1.1
Accept: text/markdown
```

And/or advertise an alternate on the HTML page:

```html
<link rel="alternate" type="text/markdown" href="/docs/quickstart.md">
```

## Citations

1. [Cloudflare AI Gateway — Token Efficiency Analysis](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide) — Equivalent markdown uses roughly 80% fewer tokens than HTML, improving agent retrieval accuracy and reducing cost
2. [agentexperience.ax — Principles of AX](https://agentexperience.ax/concepts/principles-of-ax/) — Contextual Alignment: use content negotiation for docs sites to make them respond with pure markdown when accessed from an agent
3. [Mathias Biilmann — AX in Practice](https://biilmann.blog/articles/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

---
Source: Agent Experience Principles (axprinciples.com)