Spec Contracts and Failures

What rllmdoc guarantees

rllmdoc enforces a strict contract: if it writes a file, that file meets the llms.txt specification. If it cannot produce a valid file, it writes nothing and fails with an actionable error.

There is no “best effort” mode. There is no partial output. Every generated llms.txt and llms-full.txt passes spec validation before being written to disk.

The llms.txt specification

A valid llms.txt file must contain:

1. One H1 heading — the project or site name (required)
2. A blockquote — short summary of the project (optional but recommended)
3. Zero or more H2 sections — each containing bulleted link entries

Link entries follow this format:

- [Document Title](path/to/file.md): One-line description of the document.

The Optional section name has special meaning per the spec: content listed there may be skipped by consumers that need shorter context.

What rllmdoc validates

Before generation (project validation)

These checks run before any rendering or file writing. Each failure is immediate — rllmdoc stops and reports the exact file and field.

Check	Applies to	Error message
_quarto.yml exists	Quarto projects	“Not a Quarto project”
website.title set	Quarto projects	“Missing website.title in _quarto.yml”
llms-txt: true enabled	Quarto projects	“llms-txt: true is not set”
Every rendered .qmd has title:	Quarto projects	“Missing required frontmatter field: title”
Every rendered .qmd has description:	Quarto projects	“Missing required frontmatter field: description”
DESCRIPTION exists	R packages	“Not an R package”
Title field present	R packages	“Missing Title in DESCRIPTION”
Description field present	R packages	“Missing Description in DESCRIPTION”
_pkgdown.yml exists	R packages	“_pkgdown.yml not found”

After generation (spec validation)

After rendering the llms.txt content in memory, rllmdoc validates it against the spec before writing:

Check	Error message
Content is non-empty	“Generated llms.txt is empty”
First non-empty line is an H1	“first non-empty line must be an H1 heading”
Exactly one H1 heading	“exactly one H1 heading required”
Link entries are well-formed	“malformed link entry on line N”

If any post-generation check fails, the file is not written.

During llms-full.txt assembly

Check	Error message
Rendered .md/.llms.md exists for each entry	“Rendered content not found for llms-full.txt assembly”

Missing rendered content is a hard failure. This means the project must be rendered (via quarto render or pkgdown::build_site()) before llms-full.txt can be assembled.

Error format

All errors use cli::cli_abort() and include:

• What went wrong — the specific validation failure
• Where — the file path and field name
• How to fix — actionable hint

Example:

Error in `check_quarto_yaml()`:
! Missing required frontmatter field: `description`
x File: docs/ONBOARDING.qmd

Design rationale

The strict-by-default approach exists because llms.txt is a machine-consumed format. A malformed or incomplete file silently degrades LLM context quality with no visible symptoms. Unlike a broken HTML page (which a human would notice), a flawed llms.txt file causes subtle downstream errors in AI tool behavior that are difficult to trace back to the source.

By failing loudly at generation time, rllmdoc ensures problems are caught where they’re cheapest to fix: at the source.