Return text/markdown via Content Negotiation

Return text/markdown when an agent sends Accept: text/markdown, so one canonical URL serves humans and machines the right format via HTTP.

What is content negotiation?

Content negotiation is the HTTP mechanism by which a server picks a response representation from the client's request headers: RFC 9110 calls the header-driven form proactive negotiation and defines Accept as the field a client uses to say which media types are acceptable (IETF, 2022). For the agentic web it means that a request with Accept: text/markdown gets the Markdown version of the page while a browser's Accept: text/html gets the HTML — one canonical URL, two representations, no separate .md link required. The text/markdown media type is registered by RFC 7763 (IETF, 2016).

Why does content negotiation matter for agents?

Content negotiation matters because it solves the format problem at the same URL a human uses, keeping the canonical, the analytics and the link equity on one address, whereas a markdown twin solves it at a second URL. Vary: Accept keeps that cache-safe: RFC 9110 has caches use the header fields listed in Vary as part of the cache key (IETF, 2022), so a shared cache never hands a browser the Markdown body. It is the cleanest expression of the content dimension's goal: the right format for the right client, without duplicating addresses.

How do you implement content negotiation for text/markdown?

Implement content negotiation by reading the Accept header, returning the matching representation with Vary: Accept, and confirming both formats resolve.

1. At your server or edge layer, inspect the Accept header on each request.
2. When it names text/markdown, respond with the Markdown body and Content-Type: text/markdown; charset=utf-8; otherwise serve HTML. Send Vary: Accept on both representations.
3. Verify: curl -H "Accept: text/markdown" https://yoursite/page returns Markdown with the right Content-Type, and a plain request still returns HTML.

Two Agent-Readiness Audit checks grade this: markdown-negotiation (9 of 100 points) passes when the audited URL answers Accept: text/markdown with a text/markdown response, and vary-accept (5 points) when the response carries Vary: Accept. This page is live proof — on 7 September 2026 it answered Accept: text/markdown with text/markdown; charset=utf-8 and sent Vary: Accept on both representations — and /api/analytics reports the share of this site's responses served as Markdown.

Content negotiation — frequently asked questions

Why send Vary: Accept?

Because caches use the header fields named in Vary as part of the cache key (IETF, 2022); without it a cache could serve a browser the Markdown body or an agent the HTML. The Agent-Readiness Audit awards 5 of 100 points for it.

What should the server return when Accept does not name text/markdown?

HTML. Return Markdown only when the Accept header names text/markdown; a browser's text/html or a wildcard Accept gets the HTML. Never switch formats on the User-Agent string, which is spoofable and breaks caching.

Does content negotiation replace .md twin URLs?

No, use both: negotiation keeps one canonical URL, the .md path gives agents that cannot set headers a plain link, and the link element with rel alternate and type text/markdown ties the two together. This site does all three.

Related: the content dimension · markdown twins · the Agentic Web Lexicon · audit your site

← Agent-Readiness · .md