AI Summary: Offer Markdown as an explicit HTTP representation instead of replacing the normal HTML page. Negotiate with Accept, declare Content-Type, vary caches on the selector, preserve canonical meaning and links, and keep authentication boundaries honest; deterministic Markdown improves transport clarity but does not guarantee citation.
The representation contract
A readable HTML page remains the default for browsers and people. A capable client can request a text representation by sending an Accept header such as text/markdown. The server chooses a representation it can provide and identifies the result with Content-Type. MDN describes Accept [1] as the request header that communicates which MIME types the sender understands; the response still needs to say what was actually returned.
GET /guide HTTP/1.1
Host: example.com
Accept: text/markdown
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept
ETag: "guide-markdown-v3"
Last-Modified: Sat, 23 Aug 2026 00:00:00 GMT
Vary: Accept is important when the same URI produces different representations. It tells an intermediary that the selected response depends on the request's Accept value. The HTTP semantics in RFC 9110 [2] describe content negotiation and cache variation; treat these headers as an engineering contract that must be tested through the actual cache path.
Preserve meaning, not decoration
The Markdown response should be derived from the same canonical editorial source as HTML. Keep the title, one clear H1, heading hierarchy, meaningful links, entity names, tables, updated dates, and access boundaries. Remove navigation chrome, cookie banners, tracking pixels, and layout-only fragments. Convert interactive controls into an explicit action and destination. If a page requires authentication, say that the response is incomplete or protected instead of emitting a misleading partial document.
Verification checklist
Request the same route with and without Accept: text/markdown. Confirm that the HTML default remains stable, that the Markdown response has the correct media type, and that Vary: Accept is present wherever a shared cache can store the response. Revalidate with ETag or Last-Modified where implemented, and inspect the body for credentials, private data, unstable timestamps, and hidden navigation.