---
title: 'content-md for Content Consumers'
description: 'How to serve content-md from your server — content negotiation, HTTP headers, range requests, caching, and implementation guidance for common platforms.'
date: 2026-05-05
license: 'CC-BY-4.0'
---


# content-md for Content Consumers

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.

**01 — AI Agent requests**: The AI agent sends an HTTP request with `text/markdown` as its highest preference.

```
Accept: text/markdown, text/html;q=0.8
```

**02 — Server negotiates**: The server detects the preference and checks if a content-md variant is available.

```
Content-Type: text/markdown
```

**03 — Delivers content-md**: YAML frontmatter + Markdown body is returned with standard caching headers.

```
Cache-Control: max-age=604800
```
## Response Headers

| Header | Required | Guidance |
| --- | --- | --- |
| Content-Type | Required | Must be `text/markdown; charset=utf-8`. |
| Cache-Control | Required | Set a meaningful TTL. Start with `max-age=604800` (7 days). |
| Vary | Required | Must include `Accept` so caches store HTML and content-md variants separately. |
| ETag | Recommended | Enables efficient conditional requests for re-crawls. |

## Implementation

### 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.

### Return 406 when no variant is available

If the agent requests `text/markdown` only 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**: `Cache-Control: max-age=604800` (7 days)
- **Frequently updated**: `Cache-Control: max-age=3600` (1 hour)
- **Stale-while-revalidate**: `Cache-Control: max-age=3600, stale-while-revalidate=86400`



- [Write content-md](https://contentmd.org/writers)
- [Read content-md](https://contentmd.org/consumers)
- [Reference](https://contentmd.org/reference)
- [GitHub ↗](https://github.com/OneOffTech/contentmd)