‹ all guides

Serving Markdown to AI clients

Sources checked 2026-09-15

A markdown representation can make published content easier for text-based clients to consume. Keep its facts and links aligned with the HTML page.

An HTML page carries markup, scripts and layout that a browser needs and a text-based client does not. A client that reads the raw HTML pays for all of that structure before it reaches the words. Serving a markdown form of the same page at the same address removes that overhead without changing what the page says. The words stay the same.

On this page

Negotiation

Content negotiation lets a client ask for the markdown form directly. A client sends an Accept header naming text/markdown, and the server returns the markdown form of the page in response to that same URL. A client that never sends an Accept header receives the HTML by default, so the markdown form is an addition to the page rather than a replacement for it.

Direct markdown URLs

Since v2 of the llms.txt proposal, the markdown form also has its own address. A plain page URL takes .md appended, a URL ending in .html has that suffix replaced, and a directory-style URL takes an index form. The page can also carry a link relation of type alternate for text/markdown, so a client that never sends an Accept header can still find the address by reading the page's own links. A site can also publish llms-full.txt, a single file that bundles the whole site as text, so a client can read everything in one request instead of fetching many pages.

Content parity

Markdown delivery is not a separate site. It is the same content offered in a second form, and the two forms should never drift apart. The page stays as it is for people, and a client that asks for text gets text, with the same facts and the same links. Paired with a clear llms.txt that lists where the content lives, this makes a site fast and reliable to read at machine speed.

Verification

The token saving can be large. On turva.dev the markdown form of a page has measured at a fraction of the tokens the HTML form costs for the same content, and that difference is what decides whether a client reads a page in full or runs out of budget partway through. That figure is tied to the page it was measured on and to how the receiving client counts tokens, so it is a measured example rather than a cost guarantee that holds for every client and every page. Checking a given page means comparing its own HTML and markdown byte counts, not assuming a figure measured elsewhere carries over.

turva.dev serves markdown on request and publishes llms.txt and llms-full.txt. Every page also answers at its own .md address, and /guides/markdown-for-agents and /guides/markdown-for-agents.md return the same markdown byte for byte.

Frequently asked

Why serve markdown to AI agents?

An HTML page is built for a browser, and an agent that reads it pays for all the markup, scripts, and layout it does not need. A markdown version gives the content without the wrapper, which is cheaper and less error-prone.

How does an agent request the markdown version?

Through content negotiation. An agent sends an Accept header asking for text/markdown and the server returns the markdown form at the same URL. Since v2 of the llms.txt proposal the markdown form also has its own address, the page URL with .md appended, which a client can fetch without sending any header. A site can also publish llms-full.txt to bundle the whole site as text in one request.

What does an agent pay for when it reads an HTML page?

The markup, scripts and layout it does not need. That cost is counted in tokens, so a page built for a browser is expensive for a client that only wants the text.

Sources