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 content negotiation is

Content negotiation is the standard HTTP mechanism where the server picks a response representation based on the client's Accept request header. For the agentic web it means: when an agent sends Accept: text/markdown, you return the Markdown version of the page; when a browser sends Accept: text/html, you return the HTML. One canonical URL, two representations — no separate .md link required. The media type text/markdown is registered with IANA.

Why it matters for agents

Markdown twins solve the format problem at a second URL; content negotiation solves it at the same URL the human uses, which keeps your canonical, your analytics, and your link equity on one address. An agent simply asks for the format it wants and gets it, the way the HTTP spec always intended. It is the cleanest expression of the content dimension's goal: serve the right format to the right client without duplicating addresses.

How to implement it

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

At your server or edge layer, inspect the Accept header on each request.
When it includes text/markdown, respond with the Markdown body and Content-Type: text/markdown; otherwise serve HTML. Send Vary: Accept so caches store both variants correctly.
Verify: curl -H "Accept: text/markdown" https://yoursite/page returns Markdown with the right Content-Type, while a normal request still returns HTML.

This satisfies the audit check content.content_negotiation — pass criterion: a request with Accept: text/markdown returns a text/markdown body at the canonical URL. You can request this very page with Accept: text/markdown as live proof. Confirm the text/markdown media type against the IANA registry at build, then verify the result with the Agent-Readiness Audit.

← Agent-Readiness · .md