About — acceptmarkdown.com

We kept seeing the same two implementation patterns in the wild:

Publish a few .md files and assume agents will discover them.
Check Accept, return Markdown, and stop there.

Both are better than nothing. But neither is full content negotiation. If the canonical URL still returns HTML to Accept: text/markdown, many agents will never reach your Markdown. And if you negotiate without Vary: Accept, caches eventually serve the wrong variant.

There are also useful web checkers focused on whether a URL can return Markdown at all, including Cloudflare’s isitagentready.com. That baseline check is helpful, but this project is specifically about the full negotiation contract: representation selection, cache correctness, and unsatisfiable request handling.

What we wanted to make concrete

Canonical URL behavior first, not just sibling file publication.
Spec-correct request handling: q-values, specificity, and q=0.
Spec-correct responses: Content-Type, Vary, and 406 when truly unsatisfiable.
Production realities: CDN/cache quirks and framework-specific edge cases.

Why guides and recipes are separate

Guides explain protocol decisions. Recipes translate them into concrete stack code. Keeping them separate makes it easier to audit correctness without losing copy-paste speed.

Scope

This is not a generic AI SEO site. It is a narrow implementation reference for serving Markdown and HTML representations from one URL correctly.

Production proof

We also validate this pattern against a live production implementation at roots.io, including the full negotiation path: Accept matching, Vary: Accept, canonical-URL Markdown delivery, and 406 behavior when the request is unsatisfiable.

Agent landscape

Most AI agents don’t yet send Accept: text/markdown when their built-in browse or fetch tools hit a URL. We track who does on the Status page.

Feedback

See something unclear or incorrect? Submit feedback or tweet @retlehs.