Decide whether to offer Markdown

What does this finding mean?

The report identifies this check as no-markdown-negotiation in Agent diagnostics. This diagnostic is outside the six scored categories. This is a category weight, not an automatic deduction for this finding. Read the scan detail for the measured state, overlapping signals and any score cap.

Add a negotiated representation only if a real documentation workflow benefits.

Why does this matter for AI retrieval?

These observations describe optional formats and declared content-use preferences. They earn no score points. Support varies by operator; do not assume every engine reads an optional file or honors an unofficial directive.

How do I check and resolve it?

1. Check whether your readers use agents that benefit from Markdown. This diagnostic is optional and carries no points.
2. If supported, negotiate an equivalent Markdown representation without hiding facts from normal readers. Use an appropriate Content-Type and Vary header.
3. Keep the HTML response complete. A separate format does not repair missing public content or restrictive crawler rules.

Adapt the example to the reported issue and the actual route. Placeholder names, URLs and dates must be replaced with facts from your site.

Copy code

curl -sS -D - -H 'Accept: text/markdown' 'https://example.com/docs/'
# If the response varies by Accept, send Vary: Accept.
# Keep the same public facts in the HTML and Markdown versions.

Verify the result

Request both representations and compare the substantive content. Test CDN caching so one response format is not accidentally served to every client.

Open the related tool or technical guide, then run a new scan of the affected URL. Keep unknown checks marked unknown until you have a complete response.

Copy a prompt for your coding agent

Paste this into Codex, Claude Code or Cursor from your own repository. Include the scan's exact URL and detail so the agent can verify the observation.

Copy prompt for coding agent

Investigate the scanner finding "Decide whether to offer Markdown" (no-markdown-negotiation) in this repository.
Observation: No Markdown representation was confirmed. HTML remains sufficient for this score.
Required change: Add a negotiated representation only if a real documentation workflow benefits.
Inspect the existing route, shared layouts and configuration first. Confirm the finding against the actual response before editing. Preserve intentional access restrictions, existing content and unrelated changes. Use only factual identity and date values. Make the smallest appropriate fix, verify the deployed HTML or resource response and run the relevant project checks. Explain any measurement that remains unknown. Do not promise search rankings or AI citations.
Reference: https://letthebots.in/fixes/no-markdown-negotiation/