CONCEPT Cited by 2 sources

Markdown content negotiation¶

Definition¶

Markdown content negotiation is the convention that when a client sends Accept: text/markdown on an HTTP request, the server responds with a clean markdown representation of the same URL instead of HTML. It's standard HTTP content negotiation per RFC 9110 applied to a new MIME type (text/markdown).

Why it matters for agents¶

HTML wastes tokens: navigation chrome, <div> soup, inline styles, hydration markers, ads, cookie banners, analytics scripts, related-articles widgets — none of that is content for an LLM. Markdown is ~what the LLM was trained on; {heading, paragraph, list-item, link, code-block} is all it needs.

Measured on Cloudflare's own docs (2026-04-17):

"The markdown version requires far fewer tokens — we measured up to 80 % token reduction in some cases — which makes responses faster, cheaper, and more likely to be consumed in its entirety, given the limits on context windows that most agent tools have by default."

At scale, 80 % fewer tokens per doc-fetch is 5× more calls per context window, 5× fewer dollars per agent-turn, and 5× better odds of fitting the relevant doc in a single read rather than paginating into a grep loop.

Adoption (2026-04)¶

3.9 % of the top 200 k domains handle markdown content negotiation correctly, per Cloudflare Radar.
Only 3 of 7 agents Checkly tested (February 2026) send Accept: text/markdown by default: Claude Code, OpenCode, Cursor. Reference: State of AI Agent Content Negotiation.
Second major vendor adoption (2026-04-21): Vercel enabled markdown content negotiation across vercel.com/blog and vercel.com/changelog with a Next.js rewrite-to-markdown-route implementation. Vercel's measurement: ~500 KB HTML → ~3 KB markdown = 99.37 % payload reduction on one blog post. Different measurement axis from Cloudflare's token-count savings (server-side bytes vs client-side tokens), but same load-bearing direction.

These numbers together argue for a URL-based fallback — don't assume the agent will send the header. See patterns/dynamic-index-md-fallback for Cloudflare's Transform-Rules-based /index.md approach, or patterns/link-rel-alternate-markdown-discovery for Vercel's HTML <head>-based advertisement.

Failure modes and caveats¶

Caching surface increases. A CDN now caches per-Accept variant; you need Vary: Accept at minimum or a URL- differentiated path (/index.md).
Rendering parity is load-bearing. If the markdown is a stripped-down pre-render, content can diverge from the HTML version over time unless the server renders both from one source of truth.
Most agents don't send the header. Until agent defaults change, rely on /index.md-style URL fallbacks (patterns/dynamic-index-md-fallback) and / or hidden HTML directives that tell the LLM about the markdown URL.

Seen in¶

sources/2026-04-17-cloudflare-introducing-the-agent-readiness-score-is-your-site-agent-ready — canonical wiki instance. Cloudflare's developers.cloudflare.com implements markdown content negotiation via two Transform Rules (URL Rewrite + Request Header Transform) and backs the default check in the Agent Readiness Score's Content-for-LLMs dimension. Quoted 80 % token reduction.
sources/2026-04-21-vercel-making-agent-friendly-pages-with-content-negotiation — second-vendor independent instance. Vercel implements markdown content negotiation across vercel.com/blog and vercel.com/changelog via a next.config.ts rewrite rule that routes Accept: text/markdown requests to a dedicated /md/:path* route handler. Quoted 99.37 % payload reduction (500 KB HTML → 3 KB markdown) for one blog post — a different measurement axis (server-side bytes vs client-side tokens) with a different order-of-magnitude number but consistent conclusion. Vercel also introduces markdown sitemaps as a companion primitive and <link rel="alternate"> as a third discovery layer.

Vendor-instance comparison¶

Dimension	Cloudflare (2026-04-17)	Vercel (2026-04-21)
Implementation locus	Edge (Transform Rules)	App-server (Next.js `rewrites`)
Fallback URL scheme	`/index.md` suffix	None (header-only primary)
Third-layer discovery	Hidden HTML directive	`<link rel="alternate">` tag
Measured savings	80 % tokens	99.37 % bytes
Measurement scope	Aggregate across docs	Single representative blog post
Product context	Developer docs	Blog / changelog
Also exposes	`llms.txt` + per-product splits	Markdown sitemaps (hierarchical)

Two independent implementations of the same concept landing within a week (2026-04-17 → 2026-04-21) is a strong adoption signal for the primitive.

concepts/llms-txt — complementary primitive (curate which URLs; content negotiation serves each efficiently).
concepts/markdown-sitemap — companion primitive from Vercel's 2026-04-21 post; hierarchical agent-navigable enumeration.
patterns/dynamic-index-md-fallback — Cloudflare's URL-based fallback for clients that don't send the header.
patterns/accept-header-rewrite-to-markdown-route — Vercel's Next.js-based implementation pattern.
patterns/link-rel-alternate-markdown-discovery — HTML <link rel="alternate"> tag that advertises the markdown version to agents that fetched HTML.
patterns/hidden-agent-directive-in-html — complementary signal that tells LLMs reading HTML about the markdown URL.
concepts/agent-readiness-score — where this is the default-enabled Content-for-LLMs check.
concepts/machine-readable-documentation — parent concept; markdown-over-content-negotiation is one of the documentation-as-data primitives.
systems/cloudflare-developer-documentation — reference implementation (edge-based).
systems/nextjs — Vercel's reference-implementation framework (app-server-based).