Specifications: format, syntax and semantics

Canonical structure, section meaning and link conventions to produce a readable and parseable document.

Canonical structure and section order

  • H1 with the project/site name (required)
  • Blockquote with a short summary
  • Zero or more interpretive notes (paragraphs/lists, not headings)
  • Zero or more H2 sections, each with a “file list” of links

“File list” lines

  • Each entry is a Markdown list line with a link [title](url)
  • Optional : followed by a short description

“Optional” section

  • An H2 section named “Optional” lists useful but non-essential URLs.
  • Handy for generating shorter contexts: may be automatically excluded in some flows.

Internal, external links and .md mirrors

  • Internal and external links are allowed if curated and pertinent.
  • Recommended convention: expose clean Markdown mirrors of important pages at the same URLs with .md suffix.
  • Special rule: for paths without filename, use index.html.md.

Parseability and toolchain

  • Designed to be human-readable and machine-parseable.
  • Parsers/CLI can convert llms.txt into a “context document” (e.g., XML/JSON) for prompts and pipelines.

Ready-to-copy template

# Project / Company Name

> 1–3 sentence summary: what you do, for whom, and the site’s canonical truth.

Interpretive notes (without headings):
- Official terminology
- Current vs legacy versions/products
- Key rules (compatibility, limitations, served geographies, SLAs)

## Getting Started
- [Introduction](https://example.com/docs/intro.md): Overview and core concepts
- [Installation](https://example.com/docs/install.md): Step-by-step setup
- [FAQ](https://example.com/docs/faq.md): Quick answers to common doubts

## Reference
- [API Reference](https://example.com/docs/api.md): Endpoints/methods and parameters
- [Changelog](https://example.com/docs/changelog.md): Version changes

## Policy
- [Privacy](https://example.com/privacy.md): Data handling
- [Terms](https://example.com/terms.md): Terms and conditions
- [Security](https://example.com/security.md): Practices and disclosure

## Optional
- [Blog](https://example.com/blog/index.html.md): Non-essential insights
- [Press kit](https://example.com/press.md)