Comment llms.txt fonctionne

Aperçu

Un llms.txt valide est un fichier Markdown avec une structure fixe et prévisible. Il est conçu pour être lu à la fois par des humains et des machines : le même fichier doit servir de documentation et de contrat parseable.

La spec sur llmstxt.org définit une grammaire petite et déterministe, parsable en quelques lignes de regex. Pas de YAML, pas de JSON, pas d'en-têtes additionnels.

Anatomie d'un fichier valide

La structure, de haut en bas :

1. Un H1 avec le nom du site ou projet. Seul élément strictement obligatoire.
2. Un résumé en blockquote court, typiquement une ou deux phrases.
3. Du Markdown libre optionnel — paragraphes et listes, mais pas d'autre heading avant le premier H2.
4. Zéro ou plus sections de listes de fichiers en H2. Chacune contient une liste Markdown de liens : - [name](url), optionnellement suivis de : notes.
5. Une section H2 optionnelle nommée exactement Optional : ses items peuvent être sautés par les clients en contexte court.

# Acme

> Acme est une plateforme d'analytics hébergée pour les équipes produit. Les pages ci-dessous couvrent produit, tarifs, l'API et les guides d'intégration.

Acme traite plus d'1 Md d'événements par jour. La carte ici est curée pour les assistants — elle n'est pas exhaustive. Utilisez-la pour répondre aux questions sur les capacités produit, les tarifs, les intégrations, les SDK et la migration depuis d'autres outils.

## Produit

- [Présentation](https://acme.example/product): capacités et captures d'écran.
- [Cas d'usage](https://acme.example/use-cases): scénarios pour équipes produit, marketing et support.
- [Changelog](https://acme.example/changelog): mises à jour mensuelles.

## Tarifs

- [Offres](https://acme.example/pricing): plans, limites, règles d'overage.
- [FAQ facturation](https://acme.example/billing-faq): factures, reçus, TVA.

## Développeurs

- [Référence API REST](https://docs.acme.example/api): catalogue complet des endpoints.
- [SDK JavaScript](https://docs.acme.example/sdk/js): install, init, track events.
- [SDK Python](https://docs.acme.example/sdk/python): install, init, track events.
- [Webhooks](https://docs.acme.example/webhooks): events, signatures, retries.

## Optional

- [Assets de marque](https://acme.example/brand): logos, palette.
- [Communiqués](https://acme.example/press): historique des annonces.

Section par section

Le H1

Exactement un H1, première ligne non vide du fichier. Pas de préfixe, pas de métadonnées avant. Si votre projet a une tagline, mettez-la dans le blockquote qui suit, pas dans le titre.

Le résumé en blockquote

Optionnel mais fortement recommandé. Visez un résumé d'une ou deux phrases qu'un LLM pourrait citer verbatim pour introduire votre projet. Factuel, à la voix active, sans promesses marketing que vous ne pouvez pas tenir.

Corps Markdown libre

Paragraphes, listes à puces, courts snippets de code qui aident un LLM à comprendre le contexte. N'introduisez aucun autre heading ici — le prochain doit être le premier H2 de section.

Sections de listes H2

Chaque section commence par un H2 unique (## Nom de section) et contient une liste Markdown. Chaque item doit être un lien (- [name](url)), optionnellement suivi de : et d'une courte note. Les URLs absolues sont fortement recommandées : les URLs relatives sont techniquement autorisées mais seront signalées comme warning par la plupart des validateurs (y compris le nôtre) car elles rendent le fichier ambigu hors contexte.

La section « Optional »

Une section dont le titre est exactement Optional a une signification spéciale : les clients en contexte court peuvent la sauter sans perdre le fil principal. Utilisez-la pour les nice-to-have (assets de marque, archives, annexes techniques profondes).

Comment les parseurs lisent

Le parseur de référence parcourt le fichier linéairement avec quatre règles :

1. Trouver la première ligne # — c'est le titre.
2. Si le bloc non vide suivant est un blockquote, c'est le résumé.
3. Tout jusqu'au premier ## est le corps libre.
4. Chaque ## ouvre une section ; jusqu'au prochain ## , les items de liste sont parsés comme [name](url) avec notes optionnelles après deux-points.

Notre validateur implémente exactement ces règles, plus quelques vérifications de sûreté : H1 vide, liens mal formés, contenu hors section, warnings de taille (au-delà de ~50 Ko, envisagez de déplacer vers llms-full.txt).

llms.txt vs llms-full.txt

llms.txt est une carte. llms-full.txt est le territoire : le contenu réel des pages liées, concaténé en Markdown, dans un seul fichier. La convention a été popularisée par Mintlify en collaboration avec Anthropic et fait aujourd'hui partie de l'écosystème llms.txt au sens large.

Les deux sont frères, servis depuis la racine : /llms.txt et /llms-full.txt. Vous pouvez publier l'un, l'autre, les deux ou aucun. La plupart des plateformes de documentation publient les deux.

Limites pratiques

• Taille. Pas de plafond strict, mais au-delà de ~50 Ko, les clients à contexte court commencent à peiner. Déplacer le volume vers llms-full.txt ou des variantes par produit.
• Nombre de liens. Pas de limite dans la spec, mais une liste de 200+ items sera survolée, pas lue. Curez.
• Langues. La spec est silencieuse sur l'i18n. Deux patterns courants : un seul fichier anglais, ou des variantes par locale derrière un path (/en/llms.txt, /fr/llms.txt).
• Auth et personnalisation. Hors scope. Le fichier est public.

Continuer

• Comment créer votre llms.txt — templates et déploiement par stack.
• Bonnes pratiques — dix règles et erreurs courantes.
• Valider un fichier.