How to serve Markdown to AI agents (and why it matters)

Of all the agent-readiness signals, one does more for readability than any other: returning clean Markdown when an agent asks for it. It is signal number four on the seven agents check, and the single biggest gain we made in our shop case study. Here is what it is and how to add it.

The problem it solves

A normal web page is built for human eyes: navigation, banners, cookie notices, layout and scripts. An agent that only wants your content has to fetch all of that and strip it down, guessing what is content and what is chrome. It is slow, error-prone, and sometimes it gives up. Markdown hands the agent exactly what it wants: the content, structured, with nothing to fight through.

How it works: content negotiation

The mechanism is an old, well-supported web idea called content negotiation. The agent includes a header saying which format it would prefer:

GET /products/winter-jacket
Accept: text/markdown

Your server notices the Accept: text/markdown header and, instead of the usual HTML, returns a Markdown version of the same page. A normal browser, which asks for text/html, still gets the full page. Same URL, two representations: the right one for each visitor.

How to add it

The exact method depends on your stack, but the shape is the same:

Detect the header. Check whether the incoming request's Accept header prefers text/markdown.
Return Markdown for that request. Serve a clean Markdown rendering of the page's core content (heading, body, key facts) and set the response Content-Type to text/markdown.
Leave the HTML path untouched. Browsers and search engines keep getting HTML exactly as before.

On a custom server this is a few lines of middleware. On a platform like WordPress it is a small plugin or server rule (see making a WordPress site agent-ready). You do not need to convert every page; start with the ones an agent is most likely to want, such as products, services, key docs and policies.

Test it in one line

Once it is live, confirm it from a terminal:

curl -H "Accept: text/markdown" https://yoursite.com/

If you get clean Markdown back, agents will too. If you get HTML, the negotiation is not wired up yet.

A quietly powerful side effect

This is the same idea behind agent-ready vs SEO-ready: you are not replacing your site, you are adding a second, machine-friendly representation alongside it. Cheap to do, hard for a competitor to notice you have done, and exactly the kind of signal that compounds as agent traffic grows.

Does your site serve Markdown to agents yet? Find out with a free AgentVisible scan.