# all·markdown

llms.txt: what it is and how to write one

Make your llms.txt

Fill these in and the whole file updates. Nothing is sent anywhere, and there is nothing to sign up for. 

# Project Name

> One or two sentences describing what this is. This blockquote is the summary
> a language model reads first, so make it carry the whole idea on its own.

Optional short paragraph of context that does not fit in the summary: what the
project assumes you already know, what it deliberately does not do, and any
terminology used consistently across the docs below.

## Docs

- [Quickstart](https://example.com/docs/quickstart.md): install, configure and
  run the first example in about five minutes.
- [Configuration](https://example.com/docs/config.md): every option, its
  default, and when to change it.
- [API reference](https://example.com/docs/api.md): all public functions with
  signatures and return types.
- [Deployment](https://example.com/docs/deploy.md): production checklist and
  the environment variables required.

## Examples

- [Basic usage](https://example.com/examples/basic.md): the smallest complete
  program.
- [Advanced patterns](https://example.com/examples/advanced.md): batching,
  retries and error handling.

## Optional

- [Changelog](https://example.com/CHANGELOG.md): version history.
- [Architecture notes](https://example.com/docs/architecture.md): why the
  internals are shaped the way they are.
- [Migration guide](https://example.com/docs/migrating.md): moving from 1.x.

Visual

Open in the editor Runs in this tab, nothing is uploaded.

llms.txt is a Markdown file at the root of a website - example.com/llms.txt

It is not robots.txt. That file is about permission and is read by crawlers; this one is about orientation and is read at inference time. Nothing enforces it and nothing is blocked by it: a site publishing an llms.txt is offering a map, not setting a rule.

The structure it expects

The convention is strict about shape and loose about everything else:

  1. An H1: the name of the site. The only required line.
  2. A blockquote: one or two sentences on what it is.
  3. Optional prose: any detail a reader needs before the links.
  4. H2 sections holding link lists: each link [Title](url): note.
  5. An ## Optional section, last: things safe to skip when context is short.

That last section is the part most people miss, and it is the one doing real work: it tells a model with a small budget what to drop first.

The shape

Four things, in order:

  1. An H1 with the project or site name.
  2. A single blockquote summarising it.
  3. Optional prose for context that does not fit the summary.
  4. H2 sections of links, each link followed by a colon and a note.

The blockquote is doing the most work. It is read first and often alone, so it has to carry the whole idea without depending on anything below it:

> One or two sentences describing what this is. This blockquote is the
> summary a language model reads first, so make it carry the whole idea.

The note after the colon is the difference between this file and a sitemap:

- [Quickstart](https://example.com/docs/quickstart.md): install, configure
  and run the first example in about five minutes.

“Quickstart” alone says nothing that the URL did not. The annotation says what is inside and roughly what it costs to read, which is what makes the list choosable rather than merely enumerable.

Point at Markdown where you can

Where a page has a Markdown source - quickstart.md rather than quickstart.html - link that. It skips the navigation, the cookie banner and the footer, all of which are noise around the content you meant to share. Where only HTML exists, link the HTML; a working link beats a tidy one.

The Optional section means something

## Optional is the one heading with defined semantics in the format: everything under it can be dropped when context is tight. Use it deliberately. Changelogs, architecture notes and migration guides usually belong there; the quickstart never does.

Keep it curated

The temptation is to list everything, which turns the file back into a sitemap and wastes the one advantage it has. If a section is past a dozen links, cut it to the pages that explain the most. An index that has to be read in full is not an index.

Common questions

What is llms.txt?
A proposed convention for a Markdown file at the root of a site: /llms.txt: that summarises what the site covers and links to the pages worth reading, each with a note on what it contains. The intent is to offer a clean, structured map instead of leaving a model to infer one from navigation chrome and marketing copy.
How is it different from robots.txt or sitemap.xml?
Purpose and audience. robots.txt grants or withholds permission to crawl; sitemap.xml enumerates every URL for completeness. llms.txt is curated and annotated: a short reading list of the pages that actually explain the thing, in the order a newcomer should meet them.
Why is it Markdown rather than XML or JSON?
Because it is written for a reader that handles prose well. The annotation after each link is the useful part, and a schema-shaped format would have nowhere natural to put it. Markdown also means a human can open the file and immediately see whether it is right.
What is the Optional section for?
Links that can be skipped when context is short. The format gives that heading a specific meaning, so it is the one section name worth keeping verbatim: anything under it is explicitly droppable, which is a useful signal to send deliberately.
How long should it be?
Short. It is an index, not a corpus, if a section grows past roughly a dozen links it has stopped being curation. Point at the pages that explain the most and let those pages carry the detail.
Is it a standard?
Not a ratified one. It is a proposal that has seen real adoption, particularly among documentation sites, and consumption varies by tool. The cost is a single small file, which is why plenty of sites publish one without waiting for the question to settle.

Sources