DocsContentMarkdown negotiation
Markdown negotiation
Markdown served to agents that ask for it with Accept: text/markdown.
Why an agent cares
An agent that sends Accept: text/markdown gets the page as clean text from the same address, without a separate twin to find. It only works if the answer really is Markdown, and if caches are told the address varies by Accept, or browsers can be handed the Markdown.
Adoption
Early production. Several independent organisations run it in production, though it is still niche on the open web.
Direction of travel: ▲ rising, as at .
A setting rather than a project: Cloudflare offers it as an edge toggle and docs platforms turn it on by default. A 2026-10-03 check found 14 well-known sites answering a Markdown request with Markdown, Cloudflare, Vercel and Stripe's docs among them.
| Adopter | Depth | Evidence |
|---|---|---|
| Cloudflare (Markdown for Agents) | production | blog.cloudflare.com |
| Vercel | production | vercel.com |
What we check
| Check | Severity | Raises | On whose authority |
|---|---|---|---|
| Markdown Negotiation HTML Body | high | usability | specification: HTTP Semantics: Content-Type, Vary and proactive negotiation |
Supporting documents: HTTP Semantics: Content-Type, Vary and proactive negotiation Related guidance in HTTP Semantics: Content-Type, Vary and proactive negotiation. Bad: the response is labelled text/markdown but its body is an HTML web page, so an agent that asked for Markdown pays for a full page of markup it was told was text. Fix: serve the Markdown version for this request, or label the response text/html. | |||
| Markdown Negotiation Missing Vary | medium | usability | specification: HTTP Semantics: Content-Type, Vary and proactive negotiation |
Supporting documents: HTTP Semantics: Content-Type, Vary and proactive negotiation Related guidance in HTTP Semantics: Content-Type, Vary and proactive negotiation. Bad: the Markdown response doesn't list Accept in its Vary header although the same address serves HTML to browsers, so a shared cache can hand the Markdown to human visitors. Fix: send "Vary: Accept" on the Markdown response. | |||
| Markdown Negotiation HTML Missing Vary | informational | nothing | specification: HTTP Semantics: Content-Type, Vary and proactive negotiation |
Supporting documents: HTTP Semantics: Content-Type, Vary and proactive negotiation HTTP Semantics: Content-Type, Vary and proactive negotiation permits this, so it never fails the site. Informational (does not fail Markdown Negotiation Valid): the HTML version doesn't list Accept in its Vary header either, so a cache may give an agent the web page after a browser visit. Consider sending "Vary: Accept" on both versions. | |||
| Markdown Negotiation Partially Assessed | coverage note | nothing | our own coverage |
Examples
Both run through the same checks as a live scan: the first passes, the second is flagged.
# markdownNegotiation: the home page asked for with Accept: text/markdown.
# The answer is Markdown, labelled as Markdown, and says it varies by Accept.
GET / HTTP/1.1
Accept: text/markdown
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept
# Example Store
> Handmade goods, shipped worldwide.
- [Catalog](https://example.com/catalog.md)
- [Shipping and returns](https://example.com/shipping.md)# markdownNegotiation: the home page asked for with Accept: text/markdown.
# markdownNegotiationHtmlBody: labelled text/markdown, but the body is the HTML web page.
# markdownNegotiationMissingVary: no Vary: Accept, although the same address serves HTML to browsers.
GET / HTTP/1.1
Accept: text/markdown
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept-Encoding
<!doctype html>
<html lang="en"><head><title>Example Store</title></head>
<body><h1>Example Store</h1><p>Handmade goods, shipped worldwide.</p></body></html>Specifications
| Document | Revision | Kind |
|---|---|---|
| RFC 9110 — HTTP Semantics: Content-Type, Vary and proactive negotiation | Published RFC, June 2022 | specification |
| RFC 7763 — The text/markdown media type | Published RFC, March 2016 | specification |
| Cloudflare — Markdown for Agents | Living document | guidance |
Last re-read against the published documents: .