Making docs LLM-ready: llms.txt and Markdown twins

A growing share of the people reading your documentation never open it in a browser. They ask an assistant, or their coding agent fetches the page while it writes code. Either way, a model reads your docs first — and answers with whatever it understood.

Docsheaf publishes every site in two forms: HTML for people, and Markdown for machines. Nothing needs to be configured.

Why not just let models read the HTML?#

They can, but they pay for it. A rendered docs page carries navigation, scripts, theme toggles, search boxes and footers around the content that matters. Converting that back into text loses structure in exactly the places docs need it: code samples, tabs with per-language instructions, warnings, ordered steps.

Markdown is smaller, keeps that structure, and is the format models are most fluent in.

A Markdown twin for every page#

Append .md to any published page URL and you get the same page as Markdown:

curl https://docs.example.com/quickstart.md

The Markdown uses the same dialect Docsheaf imports — GFM plus GitBook-style Liquid tags — so blocks keep their meaning:

# Quickstart

Run your first Acme job in five minutes.

{% stepper %}
{% step %}
### Install the CLI
…
{% endstep %}
{% endstepper %}

Every HTML page also advertises its twin with <link rel="alternate" type="text/markdown">, and readers can open it from the page with View as Markdown.

llms.txt: a map of the site#

llms.txt is a proposed convention for telling models what a site contains. Docsheaf serves one at the root of every site, grouped by section, with each page's description and a link to its Markdown twin:

# Acme Docs

## Documentation

- [Introduction](https://docs.example.com/introduction.md): Acme is the fastest way to ship reliable background jobs.
- [Quickstart](https://docs.example.com/quickstart.md): Run your first Acme job in five minutes.

## API reference

- [Overview](https://docs.example.com/api/overview.md): The Acme REST API lets you trigger and inspect jobs programmatically.

That makes page descriptions worth writing: they are what an agent reads when deciding which page to fetch.

llms-full.txt: the whole site in one request#

Some tools prefer to load everything at once. llms-full.txt concatenates every published page as Markdown, each one headed by its title and source URL, so an assistant can take in a whole site in a single request and still cite the right page.

The usual suspects, too#

Search engines still matter. Every site also serves sitemap.xml and a robots.txt that points to it. Unlisted sites — the ones shared with a private link — answer Disallow: / instead, so they stay out of indexes.

What's next#

These files make your docs easy for models to read. The next steps make them easy to ask: an AI assistant on every site that answers from your content, and an MCP server so agents can search and read your docs as a tool. Both are on our roadmap.

You can see all of this on our example site today: try /p/acme/llms.txt or add .md to any page.