The Markdown version for agents is broken

Short answer

The page offers a Markdown version to agents, through an answer to Accept: text/markdown or a <link rel="alternate" type="text/markdown">, but that version returns an error, an empty body or an HTML page. Agents that ask for it get nothing useful.

agent.markdown_broken · Priority: P2

What it means

The page offers Markdown to agents (as an answer to Accept: text/markdown or as a linked copy), but what comes back is an error, an empty body or an HTML page.

Why it matters for AI search

An agent that sees the Markdown link or gets a text/markdown answer trusts it and may not fall back to the HTML. A broken copy is worse than none: the agent either fails or reads an error page as your content.

This usually happens after a move or a rebuild: the .md files were not deployed, a rewrite rule points to an old path, or a middleware labels the HTML as text/markdown.

How to fix it

  1. Open the URL from the evidence and look at the status, the Content-Type and the body.
  2. If the copy is gone, deploy it again or remove the <link rel="alternate" type="text/markdown"> tag and the Link header that point to it.
  3. If the answer is HTML or empty, fix the conversion so it returns the page text as Markdown with Content-Type: text/markdown.
  4. Run "Check again" on the page report to confirm the result.

Example

curl -sS -H 'Accept: text/markdown' -D - -o /dev/null https://example.com/guide/
# expect: HTTP/2 200, 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