↓Skip to main content

Category 2: Markdown Availability

2 mins
Table of Contents
For AI agents: a documentation index is available at /llms.txt — markdown versions of all pages are available by appending index.md to any URL path.

Part of the Web Documentation Delivery Spec. The Checks Summary lists all checks with links to their definitions.

These checks evaluate whether the site serves documentation in markdown format, which agents consume far more effectively than HTML.

markdown-url-support #

  • What it checks: Whether appending .md to documentation page URLs returns valid markdown content.
  • Why it matters: Agents work dramatically better with markdown than HTML. The HTML-to-markdown conversion in web fetch pipelines is lossy and unpredictable. Sites that serve markdown directly bypass conversion issues entirely. However, agents don’t discover this pattern on their own; it needs to be signaled.
  • Result levels:
    • Pass: .md URLs return valid markdown with 200 status.
    • Warn: Some pages support .md but not consistently.
    • Fail: .md URLs return errors or HTML.
  • Recommended action:
    • Warn: Ensure all documentation pages serve markdown when .md is appended to the URL, not just some.
    • Fail: Configure your docs platform to serve .md variants for all documentation pages.
  • Automation: Full. Test against a sample of page URLs (from llms.txt, sitemap, or user-provided list).

content-negotiation #

  • What it checks: Whether the server responds to Accept: text/markdown with markdown content and an appropriate Content-Type header.
  • Why it matters: Some agents (Claude Code, Cursor, OpenCode) send Accept: text/markdown as their preferred content type. If the server honors this, the agent gets clean markdown without needing to know about .md URL patterns. Most agents don’t request markdown, but the ones that do should get it.
  • Result levels:
    • Pass: Server returns markdown content with Content-Type: text/markdown when requested.
    • Warn: Server returns markdown content but with incorrect Content-Type.
    • Fail: Server ignores the Accept header and returns HTML regardless.
  • Recommended action:
    • Warn: Set the response Content-Type to text/markdown when serving markdown content. The correct header enables optimizations in some agent pipelines.
    • Fail: Configure your server to honor Accept: text/markdown requests and return markdown content. Some agents (Claude Code, Cursor, OpenCode) request markdown this way.
  • Automation: Full.