Markdown Negotiation Not Supported for Agents

TL;DR: You do not need markdown negotiation on every site. If you want agent-friendly content delivery, support Accept: text/markdown cleanly on the routes that matter.

Treat "Markdown Negotiation Not Supported for Agents" as a practical fix cycle: isolate the break, patch the smallest safe thing, and confirm quickly. The payoff is more reliable AI crawl and citation signals over time.

This check is about content delivery, not search indexing. Some agents and crawlers can work much more efficiently if a page offers a markdown or plain-text representation when the request explicitly asks for one.

The practical bar is simple. If you support markdown negotiation, it should return a clean machine-readable response. If you do not support it, returning normal HTML is fine. What should not happen is a server error or a confusing half-state.

What Scavo checks (plain English)

Scavo makes a second request to the scanned URL with Accept: text/markdown. It then checks the returned status code, content type, and whether the body still looks like HTML.

A pass means the route returned markdown or plain text clearly. A warning means the request produced a server error or an unclear non-HTML response. An info result means markdown negotiation was not detected, which is common and acceptable on many sites.

• Scan key: ai_markdown_negotiation
• Category: AI_VISIBILITY

How Scavo scores this check

• Pass: the route returned a clear markdown or plain-text response when markdown was requested.
• Warning: the route returned a 5xx error or an unclear non-HTML response for a markdown request.
• Info: markdown negotiation was not detected for the scanned URL.

Why fixing this matters

Markdown is cheaper for agents to parse than full HTML and usually preserves the page structure they care about: headings, lists, links, and readable body text. For documentation or long-form content, that can materially improve downstream usability.

Even if you do not plan to adopt it right away, it is worth knowing whether a markdown-specific request breaks your route. That is a compatibility bug, not merely an enhancement opportunity.

Common reasons this check flags

• The origin or CDN ignores the Accept header and always returns HTML.
• The route has content negotiation logic, but the response Content-Type is misleading or missing.
• Markdown conversion works on some paths but triggers a 5xx on others.
• A reverse proxy caches one representation incorrectly because Vary: Accept is not handled properly.

If you are not technical

1. Treat this as higher priority for docs, help centers, changelogs, and other text-heavy pages. It is usually lower priority for logged-in product UI.
2. Ask engineering whether your stack can support markdown conversion at the edge, app, or route layer without destabilizing the page.
3. If the route errors on a markdown request, fix that first. After that, decide whether supporting markdown is actually worth the maintenance cost for your site.

Scavo flagged Markdown Negotiation (ai_markdown_negotiation). Please test the production route with Accept: text/markdown, stop it from erroring, and if we intend to support machine-readable delivery, return a clear markdown or plain-text response with correct content-type handling.

If you are technical

1. Request the route with curl -H "Accept: text/markdown" https://example.com/path and inspect the full response headers and body.
2. If you support markdown, return text/markdown or a clean text/plain representation and make sure caches vary on Accept.
3. If you do not support markdown, keep the route stable and deterministic. Returning normal HTML is acceptable; crashing is not.
4. Start with routes where the content is mostly prose and structure. Do not force conversion on dynamic app views that have little standalone value outside the browser.
5. Validate canonical links and internal links in the markdown output if you publish it publicly.

How to verify

• Request the live route with Accept: text/markdown and confirm the response is stable.
• Check that the body no longer looks like HTML if you intend to support markdown/plain text.
• If the response is cacheable, verify Vary: Accept or the equivalent cache separation is in place.
• Re-run Scavo and confirm the result matches your intended support level.

What this scan cannot confirm

• Scavo does not judge the quality of the markdown output in depth. It checks the live response behavior and whether the route clearly supports this negotiation pattern.
• Scavo cannot guarantee that every agent will request markdown, even if you support it.

Owner checklist

• [ ] Name one owner for this check and note where it is controlled (app, CDN, server, or CMS).
• [ ] Add a release gate for this signal so regressions are caught before production.
• [ ] After deploys that touch this area, run a follow-up scan and confirm the result is still healthy.
• [ ] Re-check AI crawler and citation signals after robots, schema, or author metadata changes.

FAQ

What does Scavo actually validate for Markdown Negotiation Not Supported for Agents?

Scavo checks live production responses using the same logic shown in your dashboard and weekly report.

Will AI visibility changes show immediately after we ship fixes?

Usually not instantly. Crawlers and answer engines refresh on different schedules, so confirm technical signals first, then monitor citations and mentions over time.

What is the fastest way to confirm the fix worked?

Run one on-demand scan after deployment, open this check in the report, and confirm it moved to pass or expected info. Then verify at source (headers, HTML, or network traces) so the fix is reproducible.

How do we keep this from regressing?

Keep one owner, keep config in version control, and watch at least one weekly report cycle. If this regresses, compare the release diff and edge configuration first.

Sources

• Cloudflare Docs: Markdown for Agents
• Cloudflare Blog: Agent Readiness
• RFC 9110: HTTP Semantics

Need stack-specific help? Send support your stack + check key and we will map the fix.