Accept:text/markdown

Accept:text/markdown is a free reference site built by Ben Word (@retlehs) that teaches developers how to implement spec-correct HTTP content negotiation so their web pages serve clean Markdown to AI agents while continuing to serve HTML to browsers — all from the same canonical URL. The site covers the full negotiation contract: representation selection, cache correctness, and unsatisfiable request handling, going beyond the common pattern of simply publishing .md sibling files.

What It Is

Accept:text/markdown is a narrow implementation reference for the Accept: text/markdown HTTP header pattern defined by RFC 7763 and RFC 9110. When an AI agent or LLM client sends a request with Accept: text/markdown, a correctly configured server responds with a Markdown representation of the page instead of HTML. Browsers, which don't send that header, continue to receive the normal HTML response. The site provides guides, copy-paste recipes for popular stacks, a live URL readiness checker, and an agent support matrix tracking which AI agents actually send the header.

Why Markdown for AI Agents

The site articulates three concrete reasons to serve Markdown over HTML to AI clients:

• Tokens: Markdown strips nav, styles, scripts, and layout wrappers, so agents spend context window budget on prose rather than DOM noise.
• Retrieval signal: Removing ads, related-content rails, and modal overlays raises the signal-to-noise ratio for RAG pipelines that embed the text.
• Latency: Less to fetch, less to parse, and less to stuff into the context window before the model starts generating.

Guides and Recipes

The site separates protocol guidance from stack-specific implementation. Guides cover fundamentals such as what content negotiation is, why Markdown matters for AI agents, how to parse Accept headers and q-values correctly, when to return 406 Not Acceptable, and how to configure Vary: Accept for CDNs including Cloudflare, Fastly, and Vercel. Recipes provide copy-paste configurations for Nginx, Caddy, WordPress, Discourse, Laravel, Rails, Cloudflare Workers, Next.js, Astro, Apache, SvelteKit, Nuxt/Nitro, Express, Go, and Django. A Cloudflare-specific shortcut is also documented: sites behind Cloudflare can enable Markdown negotiation at the edge with no origin changes required.

Readiness Checker and Agent Status Matrix

The homepage includes a live URL probe that makes a real request from the edge with Accept: text/markdown and scores the origin on four criteria: whether it serves Markdown for the header, sets Vary: Accept, rejects unsupported types with 406, and honors q-values. Results can be shared or downloaded as a scorecard image. A separate Status page tracks which AI agents currently send Accept: text/markdown when their browse or fetch tools hit a URL — the site notes that most agents do not yet send the header.

Production Proof and Scope

The site validates the pattern against a live production implementation at roots.io, covering the full negotiation path including Accept matching, Vary: Accept, canonical-URL Markdown delivery, and 406 behavior. The about page explicitly states this is not a generic AI SEO site but a narrow implementation reference for serving Markdown and HTML representations from one URL correctly.