Formatting: the grammars side by side

An llms family is a ladder of plain-markdown files. Each rung has one grammar, and the rubric judges each rung on its own grammar. This page puts them side by side; the spec page carries the verbatim spec text and the wild variants.

1. The index — llms.txt

The only file the spec defines. Structure, in order: an optional BOM; one H1 naming the site or product (the only required element); a blockquote summary of one to three sentences; free-form prose (no headings) about how to read the file; then H2 sections, each a list of links.

# Product

> One paragraph saying what this is and who it is for.

<!-- generated by docset_refine export · 2026-08-31 · 42 pages · 18,204 tokens -->

## Guides
- [Install](https://example.com/docs/install.md): package managers, the Docker image, and offline installs.

## Optional
- [Changelog](https://example.com/docs/changelog.md): every release since 1.0, newest first.

Rules the lint enforces: - [name](url): description per line (LINK_RE); descriptions of 10–25 words that carry the tokens a reader would search for; ## Optional last; the whole file under INDEX_SPLIT_BYTES = 10_000 bytes or split (§6); provenance in an HTML comment, never in frontmatter, because the spec is pure markdown.

2. The full file — llms-full.txt

Not in the spec; three grammars are in the wild. The hub emits the first and names it in a header comment so a parser never has to guess.

The hub’s header: <!-- llms-full grammar: mintlify — per page: '# Title' / 'Source: <url>' / blank / body -->. The guarantee behind it (attribute C1): splitting the full file by its grammar returns the page list of the index — a round trip with no page lost or merged.

3. The budgeted file — llms-small.txt

Same grammar as the full file, different selection: reference-class pages first, then guides, until SMALL_MAX_CHARS = 200_000 characters (about 50k tokens at CHARS_PER_TOKEN = 4) — the ceiling at which indexed docs become unstable in consumers such as Cursor. A page that does not fit is dropped whole, never truncated, and the manifest says how many pages made it.

4. The facts line — llms-facts.txt

A hub extension: the checkable claims, one per line, each anchored to the heading it came from.

## Install
https://example.com/docs/install.md
- [parameter] `--offline` installs from the local wheel cache and never touches the network. — https://example.com/docs/install.md#offline-installs · keywords: offline, wheel cache · verified-as-of: 2026-08-31

The line grammar (UNIT_RE): - [type] text — url#anchor, optionally followed by · keywords: … and · verified-as-of: YYYY-MM-DD. type is one of the twelve UNIT_TYPES: concept, fact, actionable, question, problem, statement, quote, idea, snippet, parameter, definition, change. Text is at most two sentences or 400 characters; the anchor must resolve to a heading that exists on the source page; the whole file stays within 15–30% of the prose it summarises (FACTS_RATIO_LOW, FACTS_RATIO_MED).

5. The vocabulary line — llms-vocabulary.txt

The lexical layer, spec-v2-shaped so any llms reader can open it: an H1 <Family> — vocabulary, a blockquote with the term count, then ## Terms, ## Homonyms and ## Named, not yet defined. One line per term per sense:

- **anchor** [llms.anchor] (noun): the `#fragment` on a facts-line URL that names the heading a claim came from — https://…/facts.md#anchors · aka: fragment, heading id · not: link — a link names a page, an anchor names a place on it · verified-as-of: 2026-08-31

A definition must come from a kept unit (its anchor is the line’s source); a term with no evidence goes under Named, not yet defined and never gets an invented definition. The full grammar and the sense model are in the vocabulary essay.

6. Split roots and families

When an index would exceed 10 KB the sections become subpath indexes: the root keeps the H1, blockquote and a ## Sections list of <slug>/llms.txt links, each line carrying page and token counts; a section with no further path structure is cut into part-N files of PART_PAGES = 60 pages. A family file goes one level further up: it links other indexes, never pages, carries counts on every line, and holds shared material (errors, auth, glossary) once under ## Shared. The v2 rule “most specific file wins” is what makes the nesting legal.

7. The manifest — manifest.json

Beside the files, never linked from them: files{name: {bytes, tokens}}, chars_per_token, pages, units, sections, dropped_empty_pages, acquired (how the mirror was obtained), and overrides — the hand inputs (title, summary, section_order, note) that survive regeneration. Attribute H8 checks the manifest agrees with the files it describes.

Reading order

Index first, always. Fall through to llms-small.txt when you need whole pages and have a budget, to llms-full.txt when you have none, to llms-facts.txt when you need a claim with a place to check it. The usage page turns this into a procedure.