Common llms.txt mistakes
Published:
Most llms.txt problems fall into a handful of patterns. Here are the ones our validator flags most often — and the quick fix for each.
1. More than one H1
The spec wants exactly one top-level # Title. Extra # headings confuse the structure. Demote the rest to ## section headings.
2. No blockquote summary
A one- or two-sentence blockquote right under the title is the context a model reads first. Skipping it is the single most common miss. Add one:
# Acme > Acme turns CSV files into charts. These links cover setup, the API, and pricing.
3. Sections without links (or no sections)
Empty ## sections add nothing. Each section should hold a Markdown bullet list of links to real pages. If you have no sections at all, group your key pages under headings like ## Docs and ## Guides.
4. Broken links
A file can be perfectly formatted yet point at dead pages — which wastes a crawler's budget and undermines trust. Every URL must resolve. This is the check most tools skip; we fetch each one.
5. Relative or http:// links
Use absolute https:// URLs everywhere. Models may not resolve relative paths like /docs/start, and plain http:// links look untrustworthy and can break under HTTPS-only crawling.
6. The wrong content type
Serve the file as text/plain; charset=utf-8. If your server returns text/html (a common misconfiguration), some consumers won't treat it as llms.txt.
7. A bloated, uncurated file
llms.txt is a curated index, not a sitemap dump. Hundreds of links with no descriptions bury the signal. Keep the best pages, add a short : description after each, and move secondary links to an ## Optional section.
Catch them all at once
Run your file through the validator — it scores structure, link reachability, and best practices, and tells you exactly which of the above to fix. New to the format? Start with how to create an llms.txt file.