vibecheck0.3.0
AI readinessaeomarkdown-negotiation-missinginfo

No markdown content negotiation

When an agent requests your page with Accept: text/markdown and gets HTML back, it has to parse the full DOM — navigation, scripts, styling — to recover the content. Offering a markdown representation of the same URL hands agents clean, structured text directly. It’s an advanced, optional signal, but a strong one for agent-first sites and docs.

Framework fixes
GeneralNext.jsVanilla JS

Symptoms

  • Requesting the page with Accept: text/markdown returns HTML
  • Agents parse noisy DOM instead of clean content
  • No lightweight text representation for programmatic consumers

How VibeCheck catches it

In your widget · Problems

infoaeoNo markdown content negotiation

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "aeo", issue: "No markdown content negotiation", threshold: "A request with Accept: text/markdown still returns an HTML content type" }

The same string in your widget and in your agent’s context — no screenshot, no copy-paste.

Root causes

  • The server ignores the Accept header and always returns HTML
  • No markdown source or renderer exposed for content routes

The fix

Honour the Accept header: when a request prefers text/markdown, respond with a markdown representation of the same content and a text/markdown content type. For content built from markdown already, this is often just serving the source. Add a Vary: Accept header so caches keep the two representations separate.

  1. Detect Accept: text/markdown on your content routes
  2. Return the markdown representation with a text/markdown content type
  3. Send Vary: Accept so caches don’t mix HTML and markdown responses
Negotiate on the Accept headerjs
if (req.headers.accept?.includes('text/markdown')) {
  res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
  res.setHeader('Vary', 'Accept')
  return res.end(page.markdownSource)
}

FAQ

Is markdown negotiation required?
No — it’s an optional, advanced AEO signal, most valuable for docs and agent-facing sites. VibeCheck reports it as info, not an error. Skip it if your content isn’t markdown-backed.
Why send Vary: Accept?
So shared caches and CDNs store the HTML and markdown responses separately per Accept header, instead of serving one to a client that asked for the other.
How is this different from llms.txt?
llms.txt is one static index of your key content for LLMs; markdown negotiation serves a clean markdown version of any URL on request. They complement each other — llms.txt points agents at the content, negotiation delivers it without the DOM noise.