# Markdown negotiation

This origin supports content negotiation for agents: if you send an
`Accept: text/markdown` (or `text/x-markdown`) header, the server will return
a markdown representation of the same resource instead of HTML.

## How to request markdown

```
GET /blog/how-to-build-a-membership-website HTTP/1.1
Host: circle.so
Accept: text/markdown
```

Alternatively, append `.md` to any page URL — no special header needed:

```
GET /pricing.md           → markdown for /pricing
GET /br/precos.md         → markdown for /br/precos
GET /index.md             → markdown for the homepage
```

`.md` URLs carry `X-Robots-Tag: noindex` (they duplicate the HTML page, which
stays canonical) and return `404 Not Found` when there is no such page. Every
HTML response also advertises its `.md` URL in a
`Link: </path.md>; rel="alternate"; type="text/markdown"` header.

Successful responses have:

- `Content-Type: text/markdown; charset=utf-8`
- `Vary: Accept, Accept-Encoding, Accept-Language` (or similar, always
  including `Accept`) so intermediaries cache HTML and markdown separately.
- `X-Markdown-Tokens: <integer>` — an approximate token count of the body
  (length / 4), useful for budgeting.
- `Link: <canonical-url>; rel="canonical"` — points back to the HTML URL.

If a resource has no meaningful textual representation (binary, redirect,
preview-only page) the server responds `406 Not Acceptable` and agents should
fall back to the HTML URL.

## Covered content

- `/blog/*` — blog posts (served from their source MDX)
- `/customer-stories/*` — customer stories (served from their source MDX)
- Most other marketing pages — rendered HTML converted to markdown on the fly

Localized paths (`/br/...`, `/fr/...`) are honored; untranslated content falls
back to English.