No Markdown version for AI agents
Asked for the page with Accept: text/markdown, the server sent HTML, and the page links no Markdown copy. AI agents then read the whole HTML, menus, footers and scripts included. Serving a Markdown version is optional: it is a young convention, so this is P3.
What it means
Asked with Accept: text/markdown, the page answered with HTML, and it links no Markdown copy (<link rel="alternate" type="text/markdown">). Agents then read the whole HTML, menus and scripts included. Optional: Markdown for agents is a young convention, not a standard.
Why it matters for AI search
Agents that browse for a user (and tools that load pages into a model's context) work with text, not layout. A clean Markdown version of a page is several times smaller than its HTML and keeps the headings, lists and links that matter. Some CDNs and frameworks already answer Accept: text/markdown with such a version, and llmstxt.org suggests a .md copy next to each page.
Nothing breaks without it: crawlers still read the HTML. It is a cheap improvement once access, robots.txt and content findings are fixed.
How to fix it
- Pick one way to serve Markdown: answer
Accept: text/markdownat the page's own URL, or publish a copy such as/guide/index.md. - On a CDN, turn on its Markdown conversion for agents if it has one. In a framework, add middleware that returns the Markdown version when the
Acceptheader asks fortext/markdown. - Send
Content-Type: text/markdown; charset=utf-8and, when the URL is the same as the HTML page,Vary: Accept. - Link the copy from the HTML head with
<link rel="alternate" type="text/markdown">, so agents that do not negotiate can find it too. - Run "Check again" on the page report to confirm the result.
Example
<!-- in <head>: where agents find the Markdown version -->
<link rel="alternate" type="text/markdown" href="/guide/index.md">
# the Markdown answer
Content-Type: text/markdown; charset=utf-8
Vary: Accept How to confirm the fix
After the change, press "Check again" on the report: it lists what was fixed and how the score changed.