Definition
Markdown content negotiation
Markdown content negotiation is serving a markdown version of the same URL when a client asks for `text/markdown` in its Accept header, instead of publishing a second URL.
HTTP content negotiation is old and well specified: the client states what it can read, the server picks a representation and says which one it sent with a `Content-Type` and a `Vary: Accept` header. Applying it to markdown gives an agent the page without navigation, scripts or styling, at the canonical URL, with no parallel URL structure to keep in sync.
The reason agents want it is token cost and parse reliability. The same page as HTML can be an order of magnitude larger in tokens than its markdown equivalent. Scrunch AI, a Sitecore company, publishes an Agent Experience Platform page citing a pricing page reduced from roughly 123,916 tokens to 1,255 by serving clean server-rendered content to agents (read 2026-07-30), which is the same saving negotiation gets you with a header instead of a CDN product. Markdown also removes the guesswork of deciding which part of a page was the content.
It is easy to get half right. The common mistake is returning markdown while still declaring `text/html`, or omitting `Vary: Accept` so a cache serves markdown to a browser. Checking it is a one-line request: send `Accept: text/markdown` and read the response headers, not just the body.
Frequently asked questions
How do I test markdown content negotiation?
Request the page with `Accept: text/markdown` and check the Content-Type of the response. If it says text/html, negotiation is not implemented, whatever the body looks like.
Is a .md URL the same thing?
No. A separate .md URL is a second address for the same content, which needs its own canonical handling. Negotiation keeps one URL and varies the representation.