Markdown content negotiation

Markdown content negotiation lets a server return Markdown at an existing page URL when a client requests that format.

The client requests a representation with the Accept header, such as Accept: text/markdown. The server identifies the representation it returned with Content-Type. A server may also return a supported fallback.

A clean text representation can reduce navigation and markup a tool has to process. The useful content should match the HTML page, including the facts and links a reader needs.

Test the response body and headers. If the response varies by Accept, configure caching accordingly, commonly with Vary: Accept. Otherwise a cache may deliver a representation intended for a different client.

Frequently asked questions

How do I test Markdown negotiation?

Request a page with Accept: text/markdown, then inspect the body and Content-Type. Check a browser request too, and verify that cache headers distinguish representations where needed.

Is a separate .md URL the same thing?

No. A separate .md URL is another address. Content negotiation selects a representation at the same URL.

Related

More terms