No Markdown version for AI agents

Short answer

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.

agent.no_markdown · Priority: 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

  1. Pick one way to serve Markdown: answer Accept: text/markdown at the page's own URL, or publish a copy such as /guide/index.md.
  2. 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 Accept header asks for text/markdown.
  3. Send Content-Type: text/markdown; charset=utf-8 and, when the URL is the same as the HTML page, Vary: Accept.
  4. Link the copy from the HTML head with <link rel="alternate" type="text/markdown">, so agents that do not negotiate can find it too.
  5. 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.

Check my page →

Related guides

All findings and how the score works