# Why this site exists.

Most teams are either shipping only `.md` siblings, or doing partial negotiation. This site exists to show the complete pattern.

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

1. Publish a few `.md` files and assume agents will discover them.
2. 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](https://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](https://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](/status).

## Feedback

See something unclear or incorrect? [Submit feedback](mailto:feedback@acceptmarkdown.com) or tweet [@retlehs](https://x.com/retlehs).

Know of an open-source package, guide, or writeup about Markdown content negotiation? Send it our way and we'll be happy to add a reference to it.