# llms.txt sections: file structure and Optional

> How llms.txt sections work under v2 of the proposal - link lists under H2 headings, Optional as a convention, ordering, files for site sections and languages, typical mistakes

Page: https://llms-full-txt.ru/en/specification/sections/
Site index: https://llms-full-txt.ru/en/llms.txt

:::note[Revision]
This page describes v2 of the proposal, published on August 10, 2026. The difference from v1 is on the [Changes in v2](https://llms-full-txt.ru/en/specification/changes/) page.
:::

## What a section is

A section is an H2 heading with a list of links under it. The proposal calls such a list a "file list": URLs where further detail is available.

```markdown
## Docs

- [Quick start](https://example.com/quickstart.md): first steps
- [API reference](https://example.com/api.md): methods and parameters
```

The proposal names only one section, `Optional`. Every other name is the author's choice.

## Common names

This is an observation from published files, not a requirement.

| Section | What it holds |
|---|---|
| `## Docs` | main documentation |
| `## API` | API reference |
| `## Guides` | guides and tutorials |
| `## Examples` | code examples |
| `## Reference` | reference material |
| `## Optional` | secondary links |

## The Optional section

```markdown
## Optional

- [Changelog](https://example.com/changelog.md): versions
- [Roadmap](https://example.com/roadmap.md): what comes next
- [Contributing](https://example.com/contributing.md)
```

In the v2 text, `Optional` is used "by convention" for secondary information: links an agent can skip when a shorter context is needed.

:::caution[What changed]
In v1 the section had a mechanical meaning: the `llms_txt2ctx` tool expanded a file into a ready context and used this section to decide what to drop. v2 removes context expansion by a tool from the proposal, and the special meaning of the section goes with it. The section is still allowed, but you cannot rely on an agent treating it in any particular way.
:::

## Order

1. The H1 - the project name.
2. A blockquote with a short summary.
3. Details without headings.
4. Sections with the main links.
5. `Optional` last.

The proposal fixes the order of the first three parts. The order of sections among themselves is up to the author; the most important ones go first.

## Example

```markdown
# FastHTML

> FastHTML is a python library which brings together Starlette, Uvicorn, HTMX, and fastcore's `FT` "FastTags" into a library for creating server-rendered hypermedia applications.

Important notes:

- Although parts of its API are inspired by FastAPI, it is *not* compatible with FastAPI syntax and is not targeted at creating API services
- FastHTML is compatible with JS-native web components and any vanilla JS library, but not with React, Vue, or Svelte.

## Docs

- [FastHTML quick start](https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md): A brief overview of many FastHTML features
- [HTMX reference](https://github.com/bigskysoftware/htmx/blob/master/www/content/reference.md): Brief description of all HTMX attributes, CSS classes, headers, events, extensions, js lib methods, and config options

## Examples

- [Todo list application](https://github.com/AnswerDotAI/fasthtml/blob/main/examples/adv_app.py): Detailed walk-thru of a complete CRUD app in FastHTML showing idiomatic use of FastHTML and HTMX patterns.

## Optional

- [Starlette full documentation](https://gist.githubusercontent.com/jph00/809e4a4808d4510be0e3dc9565e9cbd3/raw/9b717589ca44cedc8aaf00b2b8cacef922964c0f/starlette-sml.md): A subset of the Starlette documentation useful for FastHTML development.
```

The example comes from the proposal text.

## Several files on one site

v2 defines what a file in a subpath means: it covers the URLs under its path, and where more than one file applies, agents should use the most specific one.

```text
/llms.txt          -> the whole site
/docs/llms.txt     -> documentation only
/api/llms.txt      -> API only
```

The page `/docs/install/` is covered by both the root file and `/docs/llms.txt`; an agent should use the second.

### Multilingual sites

The same rule lets a file sit in a language section:

```text
/llms.txt        -> the whole site
/ru/llms.txt     -> the Russian section
/en/llms.txt     -> the English section
```

The proposal does not say which language the root file of a multilingual site should use. The question is open in the proposal repository.

## Grouping links

By content type:

```markdown
## Tutorials

- [Beginner tutorial](https://example.com/tutorial/basic.md): first steps, 30 minutes
- [Advanced tutorial](https://example.com/tutorial/advanced.md): two hours

## API Reference

- [REST API](https://example.com/api/rest.md): HTTP methods
- [SDK](https://example.com/api/sdk.md): client libraries
```

By platform:

```markdown
## JavaScript

- [npm package](https://example.com/js/install.md): installation and usage

## Python

- [PyPI package](https://example.com/python/install.md): installation with pip
```

## What to avoid

**Too many sections.** Ten sections with one link each read worse than three sections with clear notes.

**Sections without links.** A heading with no list gives an agent nothing.

**A file with no links at all.** In an analysis of the [Common Crawl](https://commoncrawl.org/blog) corpus, 23% of published `llms.txt` files contain not a single link. Such a file does not do its job: the agent has nowhere to go.

**The same link in several sections.** One link, one section.

**Links to pages that are hard for a model to read.** If a page has a Markdown version, link to that.

More in [Best Practices](https://llms-full-txt.ru/en/guides/best-practices/).

## How others do it

Documentation files change, so section names are not quoted here: opening the files is more reliable. All URLs were checked on October 3, 2026.

- [developers.openai.com/llms.txt](https://developers.openai.com/llms.txt) - a root file with nested indexes for `/api`, `/codex`, `/commerce`
- [docs.stripe.com/llms.txt](https://docs.stripe.com/llms.txt) - a large index with no `llms-full.txt`
- [developers.cloudflare.com/llms.txt](https://developers.cloudflare.com/llms.txt) - an index by product
- [fastht.ml/docs/llms.txt](https://www.fastht.ml/docs/llms.txt) - a file in a subpath, the example from the proposal itself