---
name: markdown-negotiation
description: Return Markdown content when agents send Accept: text/markdown
---

# Markdown content negotiation

Use standard HTTP content negotiation: when a client sends `Accept: text/markdown`, return a Markdown version of the page; HTML stays the default for browsers. This is **not** a new protocol — it's the existing `Accept` header (RFC 9110) applied to the `text/markdown` MIME type. There is no `.well-known/` URL for it.

## Requirements

- Honor `Accept: text/markdown` on at least your main content routes
- Respond with `Content-Type: text/markdown; charset=utf-8` and HTTP 200
- The body should be a clean Markdown rendering of the same content (no nav chrome, no tracking scripts)
- Optional: include the URL of the Markdown alternative as a `Link` response header: `Link: <foo.md>; rel="alternate"; type="text/markdown"`

## Example (Next.js middleware)

```ts
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const accept = req.headers.get("accept") ?? "";
  if (accept.includes("text/markdown")) {
    return NextResponse.rewrite(new URL(req.nextUrl.pathname + ".md", req.url));
  }
}
```

Then expose `/<route>.md` routes (App Router `route.ts` returning `text/markdown`).

## References

- [MDN — HTTP Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation) (the underlying mechanism)
- [RFC 9110 §12.5.1 — Accept](https://www.rfc-editor.org/rfc/rfc9110#name-accept) (spec)
- [Cloudflare — Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) (tutorial, branded as a feature)