Guides

Serve Markdown to agents

AI agents ask for text/markdown. One middleware returns it from your existing HTML — and the detector now fails the installs that forget Vary: Accept.

Updated 2026-11-08

On this page

Guide · Markdown for agents

The same URL answers agents with Markdown and browsers with HTML. One middleware, five pitfalls handled for you.

  1. Why negotiate Markdown

    Agents parse HTML badly and pay tokens for chrome they never need. Content negotiation answers the same URL with Markdown when the client sends Accept: text/markdown, while browsers keep getting the page they expect. Cloudflare ships this on Pro; the same behaviour is available here as a zero-dependency package.

    Client sends: Accept: text/markdown

  2. Install the middleware

    Wrap your fetch handler with markdownNegotiation() from @visdenda/agent-watch/markdown. It re-fetches the same URL once with Accept: text/html (recursion-safe), converts with Vary merged and token estimates attached, and falls back to the original HTML on any failure — your pages never go down. Check your own site with the public Markdown negotiation checker.

    export default markdownNegotiation().wrapFetch(…)

  3. Five pitfalls to avoid

    • Ignoring q-values: text/html;q=0.9 must beat text/markdown;q=0.5.
    • Setting Vary instead of merging it — CDNs then serve Markdown to browsers.
    • Re-fetching without rewriting Accept — an infinite loop on the same URL.
    • Converting non-2xx, non-HTML or oversized bodies instead of falling back.
    • Dropping content-signal when the origin already declared it.

    Detector: missing Vary: Accept is now a fail, not a pass