For Content Consumers

Serve content-md from your server.

Implementation guide for serving content-md: content negotiation, response headers, range requests, caching strategy, and patterns for common server stacks.

How It Works

Content negotiation.

content-md uses the standard HTTP Accept header. AI agents that know the protocol get the optimized version. Others get HTML as usual.

Request

AI Agent requests

The AI agent sends an HTTP request with text/markdown as its highest preference in the Accept header.
Accept: text/markdown, text/html;q=0.8
Negotiate

Server negotiates

The server detects the preference and checks if a content-md variant is available for the requested resource.
Content-Type: text/markdown
Deliver

Delivers content-md

YAML frontmatter + Markdown body is returned with standard caching headers. Start with a 7-day expiry.
Cache-Control: max-age=604800
Response Headers

Signal support correctly.

A correct content-md response requires a small set of HTTP headers. Get these right and agents can discover, cache, and request content-md reliably.

Header Required Guidance
Content-Type Required Must be text/markdown; charset=utf-8 for all content-md responses.
Cache-Control Required Set a meaningful TTL. Start with max-age=604800 (7 days) for stable content. Shorter for frequently updated pages.
Vary Required Must include Accept so that caches store HTML and content-md variants separately for the same URL.
ETag Recommended A content hash or revision identifier enables efficient conditional requests (If-None-Match) for re-crawls.
Full response headers example
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Cache-Control: max-age=604800
Vary: Accept
Accept-Ranges: x-frontmatter, bytes
ETag: "a3f8c2d1"
Implementation

Common patterns.

content-md works with any server that can inspect request headers and return different responses. The pattern is the same across frameworks: check the Accept header, serve the right variant.

Generic — pseudo-code
// Check if the client prefers text/markdown
if request.accept.prefers("text/markdown") {
  if markdownVariantExists(request.path) {
    response.setHeader("Content-Type", "text/markdown; charset=utf-8")
    response.setHeader("Cache-Control", "max-age=604800")
    response.setHeader("Vary", "Accept")
    return markdownVariant(request.path)
  }
}
// Fall through to HTML response as normal

Pre-generate, don't convert on the fly

Generate the .md variant at publish time and store it alongside the HTML. Serving a static file is fast, predictable, and cacheable. Live HTML-to-Markdown conversion is fragile and slow.

Return 406 when no variant is available

If the agent requests text/markdown only (no HTML fallback) and no variant exists, return 406 Not Acceptable. If the agent listed HTML as a fallback, serve HTML instead.

The Vary header is non-optional

Without Vary: Accept, a CDN or proxy may serve a cached Markdown response to a browser, or vice versa. This is a common misconfiguration that serves the wrong format to browsers or agents.
Caching

Content-md is cache-friendly by design.

Text-only, no session state, no personalisation. Content-md responses cache well at the CDN layer. A well-cached content-md document costs your origin server nothing at scale.

Stable content

Articles, documentation pages, reference content that rarely changes.
Cache-Control: max-age=604800

7 days. Safe for most editorial content.

Frequently updated

News articles, changelogs, pricing pages, or content updated at least weekly.
Cache-Control: max-age=3600

1 hour. Balances freshness and origin load.

Stale-while-revalidate

Serve stale content immediately while refreshing in the background.
Cache-Control: max-age=3600,
 stale-while-revalidate=86400

Recommended for high-traffic pages.