What is Markdown content negotiation and why should a site support it?
Markdown negotiation serves two versions of a page from one URL: HTML to a browser, and plain text without layout to any agent sending an Accept: text/markdown header. The agent receives only what it actually reads and spends several times fewer tokens. No new URLs are created for it.
When a language model agent opens your page it receives the same HTML a browser
does: navigation, footer, consent banner, <script> blocks, CSS classes. Its
first job is to throw all of that away and keep the text.
You can do that job for it. And it is cheaper for both sides.
How it works
The agent sends an ordinary request with one extra header:
Accept: text/markdown
The server responds at the same URL with markdown instead of HTML — headings, paragraphs, lists, links. A browser never sends that header and keeps getting HTML.
One URL, two representations. This is a standard HTTP mechanism called content negotiation, and it needs neither a new protocol nor a library.
What it saves
The exact number depends on the layout, but the order of magnitude is constant. On a typical content page the HTML is 5–10 times larger than the text it carries: most of it is classes, attributes, inline styles and scripts.
For an agent that translates directly into tokens. A page costing 8,000 tokens as HTML costs around 1,200 as markdown — the same content, minus everything the model discards anyway.
What matters more than the price is that more of your page fits the context window. A long article that used to be truncated halfway now arrives whole.
Three things that are non-negotiable
Vary: Accept on both responses. Without it an intermediate cache can serve
markdown to a browser or HTML to an agent. The fault stays invisible until
somebody reports that your page "shows code".
No .md URLs. /pricing.md would be another copy of the same page in the
search index — exactly the problem ?lang= parameters create. Negotiation
happens at the same URL or it does not happen.
Public indexable pages only. A page behind a login or carrying noindex
would, in markdown, be the same content in a second form with none of the
protection.
What else to declare
Link headers (RFC 8288) travel with the response. Two of them are worth
sending:
Link: </llms.txt>; rel="describedby"
Link: <https://example.com/pricing>; rel="alternate"; type="text/markdown"
The first points to llms.txt — a site map for agents. The second announces that this URL has a markdown representation, and it is the only way to discover the negotiation without guessing.
Does it help SEO?
No, and claiming otherwise would be marketing. It has no effect on Google rankings, and the markdown version is not indexed.
The benefit is different and narrower. An agent that reads your page fully and cheaply uses your content more often than one left with half of it. That is a GEO question, not an SEO one — it is about whether your text makes it into the answer at all, not about what position you hold.
The honest limit: this is a small improvement for sites that already did everything else. If your pages are not indexed or have no structure, markdown will not help — start with how AI decides what to cite.
How to check
One command is enough:
curl -H "Accept: text/markdown" -i https://example.com/
If the response shows Content-Type: text/markdown and Vary: Accept,
negotiation works. If it shows HTML, it does not.
The free scan checks the broader agent surface: llms.txt, content
signals in robots.txt, Link headers, and whether your pages are reachable at
all by a bot that runs no JavaScript.
Related articles
The same topic from another angle — each answers its own question:
How this feeds into the score is described under what we check.
Sources
What this text is based on — primary sources, not retellings:
Frequently asked
Do I write the markdown version by hand?
No, and you should not. Markdown is generated from the same source; a hand-written second version starts lying within a month.
Will Google treat this as cloaking?
No, as long as the content matches. Cloaking is **different** content for different visitors. This is the same text in another format — the same principle as serving a page compressed or uncompressed.
Which agents use it today?
Support is uneven and growing. That is why the `Link` header matters: it lets an agent that does not yet ask for markdown find out it exists.
Is it worth doing on a small site?
Only after everything else. This is the last percent, not the first step.
Check yours
A free scan shows which of the things described here your site already does, and which it does not.