<!-- llms-explorer twin of https://llms-explorer.com/reference/formatting/ · generated 2026-08-31 -->

# Formatting: the grammars side by side

The index, the three full-file grammars, the facts line, the small file, the vocabulary line, the split root and the manifest — on one page.

<!-- hand page · reference/formatting · condensed from docs/site/components/03-reference.md §3 · 2026-08-31 -->

An llms family is a ladder of plain-markdown files. Each rung has one grammar, and the
[rubric](/reference/attributes/) judges each rung on its own grammar. This page puts them side by
side; the [spec page](/reference/spec/) 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.

```markdown
# 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.

| Grammar | Page block | Who |
|---|---|---|
| Mintlify | `# Title` / `Source: <url>` / blank / body; blank lines between pages | Mintlify sites, Claude Code docs, **the hub** (`GRAMMAR_NOTE`) |
| Anthropic YAML | site H1, `---`, per page `## Heading` + YAML (`title:` / `url:` / `description:`) + raw MDX | platform.claude.com |
| Cloudflare frontmatter | YAML frontmatter, a "Documentation Index" blockquote, `# Title`, `[View as Markdown](…/index.md)`, body | developers.cloudflare.com |

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](/essays/vocabulary/).

## 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](/reference/usage/) turns this into a procedure.