llms.txt: pourquoi Lighthouse échoue sans liens Markdown

Le fichier llms.txt s’est imposé comme un nouveau point de repère pour le web “agentique” — un web où des agents (LLM, navigateurs assistés, crawlers d’IA) lisent et exécutent des instructions plutôt que de seulement afficher des pages. Problème: l’audit “Agentic Browsing” de Lighthouse traite ce fichier .txt comme un document Markdown. Résultat, si vos liens ne sont pas au format Markdown, l’outil peut conclure à tort que votre llms.txt “ne contient aucun lien”, et faire échouer l’audit. La bonne nouvelle? Un correctif de cinq caractères par lien suffit souvent à transformer un échec en réussite totale. 🧩

Qu’est-ce que llms.txt et pourquoi cela compte pour l’agentic browsing ? 🤖

Le fichier llms.txt est un manifeste lisible par machine, posé à la racine d’un site (https://votredomaine.com/llms.txt). Il décrit où et comment un agent doit découvrir vos contenus, sections, flux et formats de données utiles. En clair, c’est une carte d’orientation pour les systèmes d’IA qui cherchent des ressources fiables à explorer, citer ou utiliser.

Dans l’écosystème naissant de l’agentic browsing, llms.txt joue le rôle que robots.txt et sitemaps.xml ont joué pour le SEO classique: un standard simplifié qui donne des indices forts sur la structure d’information d’un site, sans avoir à exécuter de JavaScript ou à déduire des intentions depuis des interfaces pensées d’abord pour les humains.

Objectifs concrets de llms.txt

– Aider les agents à trouver les bons contenus plus vite (listes d’URL, motifs d’URL, endpoints d’API, flux RSS/Atom).

– Communiquer des priorités, regroupements et conventions de nommage.

– Réduire l’ambiguïté et les erreurs d’extraction en fournissant des liens et des descriptions explicites.

La syntaxe de référence: du Markdown, même dans un “.txt”

Bien qu’il porte l’extension .txt et soit servi avec le type MIME text/plain, le format attendu pour llms.txt est celui d’un document Markdown minimal. Chaque section est généralement une liste à puces dont chaque élément contient un lien au format Markdown, suivi d’une description séparée par un “:”. Exemple:

- [Articles](/blog): Tous les billets et analyses
- [Podcasts](/podcast): Épisodes, transcripts et flux RSS
- [API publique](/api): Endpoints et schémas

Ce détail est essentiel: de nombreux outils (dont Lighthouse) ne considèrent un item comme “lien” que s’il est encodé en syntaxe Markdown [texte](URL). Des URLs “nues” ou des tirets n’entrent pas dans leur logique de parsing.

Comment Lighthouse évalue llms.txt aujourd’hui 🔎

Depuis Lighthouse 13.3.x, Chrome propose une catégorie “Agentic Browsing” aux côtés de Performance, Accessibilité, Bonnes pratiques et SEO. Cette catégorie regroupe plusieurs contrôles, notamment un audit consacré à la “découvrabilité de llms.txt”.

Les audits typiques de la catégorie Agentic Browsing

Sans entrer dans le détail du code interne, on y retrouve notamment:

– Un contrôle de l’arborescence d’accessibilité exploitable par des agents.

– Une mesure de stabilité visuelle (utile pour l’automatisation et l’exploration pilotée).

– Des vérifications WebMCP (déclarations d’outils/intentions agentiques naissantes).

– Et, surtout pour nous ici, un test “llms.txt” focalisé sur la présence de liens reconnus.

Particularité: le score n’est pas un 100/100 classique; Lighthouse peut afficher un ratio de passes/échecs, signe que la normalisation du “web agentique” est encore en évolution.

Ce que l’audit “llms.txt” mesure réellement

– La parsabilité: l’outil cherche des liens au format Markdown. Si vos lignes ne respectent pas la forme [texte](URL), elles ne seront pas comptées comme des liens.

– La découvrabilité: l’audit vérifie que le fichier existe et qu’il contient des items exploitables par un agent automatisé.

– Le strict minimum technique: Lighthouse ne juge ni l’exhaustivité, ni la pertinence éditoriale, ni la fraîcheur des données. Il évalue surtout si un parseur peut extraire des liens sans ambiguïté.

Pourquoi un fichier “lisible par un humain” peut échouer

Beaucoup d’éditeurs commencent par écrire un llms.txt “naturel”: listes de sections, URLs en clair, séparateurs au tiret. Pour un humain, c’est compréhensible; pour un parseur qui attend du Markdown, cela équivaut à “aucun lien”. Ce décalage explique l’erreur fréquente “File does not appear to contain any links”. ⚠️

Diagnostiquer l’erreur: où et comment lancer l’audit 🧪

Vous pouvez exécuter l’audit de deux façons rapides, selon votre préférence.

Via Chrome DevTools

– Ouvrez votre site dans Chrome.

– Ouvrez DevTools (Ctrl+Shift+I sous Windows/Linux, Cmd+Option+I sur macOS).

– Onglet Lighthouse → cochez “Agentic Browsing”.

– Lancez l’analyse sur l’URL racine.

Si l’audit échoue pour llms.txt, vous verrez un message indiquant l’absence de liens détectés ou une recommandation de format.

Via la CLI Lighthouse

Pour automatiser et intégrer à vos workflows CI, la CLI est très pratique:

npx lighthouse@latest https://votresite.com --only-categories=agentic-browsing

Le rapport indique alors, par audit, s’il est “pass”, “fail” ou “not applicable”. En cas d’échec du test llms.txt, cherchez une mention de type “le fichier ne semble contenir aucun lien”.

Le correctif en cinq caractères par lien 🛠️

La solution la plus rapide consiste à convertir chaque lien en syntaxe Markdown, et à remplacer le séparateur qui précède la description par “: ” (deux caractères: les deux-points et l’espace). D’où l’idée d’un “correctif en cinq caractères”: vous ajoutez “[]()” autour de vos liens et remplacez “-” par “: ” devant la note.

Exemple avant/après

Avant (lisible, mais non parsable par Lighthouse):

- Accueil: / - Rubriques clés, dernières publications
- Articles: /blog - Tous les billets
- Épisode: /episode/[slug] - Notes, transcript, lecteur audio

Après (lisible et parsable):

- [Accueil](/): Rubriques clés, dernières publications
- [Articles](/blog): Tous les billets
- [Épisode](/episode/[slug]): Notes, transcript, lecteur audio

Sans rien changer au contenu ni au type MIME, l’audit détectera correctement des liens et considérera votre fichier llms.txt conforme aux recommandations de formatage. ✅

Règles minimales à respecter

– Chaque entrée de liste commence par “- ” (tiret + espace).

– Le libellé cliquable est enfermé dans des crochets: [Texte du lien].

– L’URL est en parenthèses immédiatement après: (https://exemple.com/chemin) ou (/chemin).

– Une description optionnelle suit, précédée d’un “: ”.

– Évitez les URLs “nues” sans la structure [texte](url), elles seront ignorées par l’audit.

Convertir en masse: trois options rapides

– Recherche/remplacement avec regex dans votre éditeur: transformez “- Nom: /chemin – Desc” en “- [Nom](/chemin): Desc”.

– Script ponctuel (Node, Python) pour entourer automatiquement vos URLs détectées et positionner les libellés depuis le texte avant les “:”.

– Adaptation de votre générateur (CMS/plugin/SSG) pour émettre nativement du Markdown selon la convention ci-dessus.

Bon format ≠ bon contenu: comment juger la qualité de votre llms.txt 🧠

Passer l’audit n’est qu’une première étape. Un llms.txt “propre” peut être pauvre sur le fond, tandis qu’un llms.txt riche écrit en texte libre peut échouer à cause de la forme. Or ce que recherchent les agents, ce n’est pas seulement une liste de liens parsables — c’est une cartographie utile de votre offre d’information.

Ce que Lighthouse ne vérifie pas

– Exhaustivité: vos sections clés sont-elles toutes représentées?

– Hiérarchie et clarté: les regroupements aident-ils un agent à prioriser?

– Cohérence des libellés: mêmes noms pour mêmes concepts à travers le site?

– Stabilité des URL patterns: motifs robustes, sans dépendre de paramètres éphémères?

– Mise à jour: le fichier est-il rafraîchi à chaque évolution de l’IA, du contenu ou de l’architecture?

Check-list éditoriale pour un llms.txt utile

– Couvrez les zones de valeur: articles, guides, docs, API, données téléchargeables, flux.

– Donnez des descriptions concises et orientées usage (“Transcripts complets”, “Endpoint JSON paginé”, “Flux RSS des épisodes”).

– Déclarez vos motifs d’URL (p. ex. /episode/[slug], /blog/[année]/[mois]/[slug]).

– Ajoutez les flux (RSS/Atom/JSON Feed) si disponibles.

– Liez vers vos politiques (citations, droits d’usage des données, taux de rafraîchissement).

– Respectez une terminologie stable: un agent apprend vos conventions au fil de la page.

Gouvernance et maintenance

– Nommez un “owner” du fichier llms.txt (marketing technique ou SEO technique).

– Versionnez-le (Git) et validez chaque changement via revue.

– Programmez une revue trimestrielle: nouveaux produits, sections, flux, schémas?

– Surveillez les 404/410: mettez à jour les liens cassés rapidement.

CMS et plugins: les automatismes sont pratiques, mais pas infaillibles ⚙️

De nombreux CMS et extensions proposent désormais une génération automatique de llms.txt. C’est souvent un bon point de départ, car ces générateurs émettent déjà des liens au format Markdown, ce qui fait “verdir” l’audit. Cependant, ne vous contentez pas du défaut.

Limites des fichiers auto-générés

– Couverture partielle: seules certaines taxonomies ou types de contenu sont exportés.

– Descriptions génériques: parfois trop vagues pour être réellement utiles.

– Absence de sections stratégiques (API, datasets, documentation interne/externe).

La bonne approche: hybride

– Laissez le CMS produire l’ossature (sections de base).

– Ajoutez manuellement les zones à forte valeur métier.

– Normalisez les libellés et les descriptions pour rester cohérent.

Tests et monitoring en continu

– Intégrez l’audit Lighthouse à votre CI/CD (exécution CLI après chaque déploiement).

– Définissez un seuil minimal (ex. toutes les sous-parties de l’Agentic Browsing doivent “pass”).

– Surveillez le temps de réponse et l’accessibilité du fichier (uptime + taille + hash) pour repérer des régressions.

FAQ express sur llms.txt ❓

Dois-je changer le Content-Type de llms.txt en text/markdown ?

Non indispensable. Lighthouse accepte un fichier servi en text/plain tant que la structure interne est Markdown (liens [texte](URL)). Changer le type MIME peut être logique à terme, mais l’essentiel est la parseabilité. Priorisez le format des liens et la qualité éditoriale.

Un sitemap.xml bien renseigné remplace-t-il llms.txt ?

Non. Un sitemap est centré sur la découverte d’URLs et la fraîcheur (lastmod, priorité relative), tandis que llms.txt communique une intention éditoriale et des points d’entrée contextualisés pour des agents. Les deux sont complémentaires.

Quel est l’impact SEO actuel de llms.txt ?

Il n’existe aucune garantie de gains de classement organique. L’intérêt de llms.txt est plutôt d’ordre “machine-first”: réduire la friction d’accès à vos ressources par des agents et expérimentations d’IA. C’est un investissement d’architecture et de découvrabilité qui peut porter ses fruits à mesure que l’écosystème agentique mûrit.

Plan d’action en 15 minutes ⏱️

– Minute 1: Vérifiez l’existence de https://votresite.com/llms.txt.

– Minutes 2–5: Lancez Lighthouse (DevTools ou CLI) et notez le statut de l’audit llms.txt.

– Minutes 6–10: Convertissez vos lignes en format Markdown si nécessaire: “- [Libellé](/url): Description”.

– Minutes 11–12: Réexécutez l’audit. Assurez-vous que llms.txt passe.

– Minutes 13–15: Ajoutez au moins deux sections à forte valeur (flux RSS, motifs d’URL, API) et des descriptions orientées usage.

Bonnes pratiques avancées pour un llms.txt robuste 🌐

1) Pensez “modèle de données”, pas “mise en page”

Un agent ne “voit” pas votre design. Décrivez votre site en entités et relations: Articles, Épisodes, Datasets, API, Auteurs, Thématiques. Structurez vos listes par cas d’usage: “Découvrir les articles récents”, “Lister tous les épisodes”, “Télécharger les données”.

2) Documentez les motifs et états d’URL

Les agents apprécient les patrons stables. Indiquez clairement: /article/[slug], /episode/[slug], /api/v1/[ressource], et précisez si des redirections, paramètres ou étapes d’authentification existent. Vous pouvez l’exprimer dans la description après les “:”.

3) Exposez les meilleures sources de fraîcheur

Ajoutez vos flux (RSS/Atom/JSON Feed) et aidez l’agent à privilégier ces endpoints pour la veille. Donnez un indice de fréquence de mise à jour dans le texte descriptif.

4) Signalez les contraintes d’usage et de citation

Précisez les règles de citation, les licences de contenus, et les préférences d’attribution. Cela évite des interprétations hasardeuses par des systèmes qui chercheront à réutiliser vos données.

5) Minimisez les dépendances JavaScript côté client

llms.txt doit suffire pour orienter un agent vers des contenus accessibles sans exécuter de scripts. Quand vous référencez des pages ou API, favorisez des rendus server-side, des fichiers statiques ou des endpoints documentés.

6) Testez la résilience

Faites quelques essais de parsing local (ex. librairies Markdown) pour vérifier que vos liens ressortent bien, que les descriptions n’introduisent pas d’ambiguïtés et que les caractères spéciaux (parenthèses dans une URL, espaces encodés) n’interrompent pas la lecture.

Exemples de sections utiles à inclure dans llms.txt 📌

– [Accueil](/): Porte d’entrée, collections et nouveautés.

– [Articles](/blog): Tous les articles; format: texte, images; pagination standard.

– [Épisodes](/podcast): Show notes, transcripts, lecteur audio.

– [Flux RSS](/feed.xml): Mises à jour des articles récents.

– [Flux Podcast](/podcast/feed.xml): Flux compatible lecteurs.

– [Glossaire](/glossaire): Définitions de termes utilisés sur le site.

– [API](/api): Endpoints publics; authentification si besoin; limites de taux.

– [Données](/data): Jeux de données téléchargeables; formats CSV/JSON.

– [À propos](/a-propos): Politique d’attribution et contact.

Notez bien la forme: chaque item est une puce avec un lien Markdown et une brève description. Cette cohérence aide autant Lighthouse que les agents réels. 💡

Erreurs fréquentes et comment les éviter ❌ → ✅

– URLs nues (https://… sans [texte](…)): non détectées → entourez-les en Markdown.

– Tirets comme séparateurs de description (“-”): préférez “: ” après la parenthèse fermante.

– Libellés trop vagues (“Contenu”, “Ressources”): remplacez par des noms métiers clairs (“Guides”, “Études de cas”, “Données ouvertes”).

– Multiplication de liens vers des pages peu utiles aux agents (pages d’interactions très humaines): concentrez-vous sur des sources stables et riches.

– Oubli des flux: ajoutez RSS/Atom; c’est un accélérateur de découverte pour les systèmes.

Mesurer ce qui compte vraiment 📏

Un llms.txt qui “passe au vert” signifie surtout que vos liens sont facilement extrayables. C’est nécessaire, pas suffisant. Les critères de réussite réels pour votre organisation sont ailleurs:

– Vos contenus prioritaires sont-ils trouvés et utilisés correctement par des systèmes tiers?

– Les citations/reprises respectent-elles votre politique d’attribution?

– Les ingénieurs ou partenaires qui consomment vos données comprennent-ils rapidement “où est quoi” grâce à llms.txt?

Traitez l’audit Lighthouse comme un test d’intégration de base. Puis bâtissez votre avantage compétitif sur la clarté, la couverture et la fraîcheur.

Conclusion: faites simple, parseable et utile 🚀

Si votre llms.txt “échoue” dans Lighthouse alors que vous voyez pourtant des URLs dans le fichier, le diagnostic est presque toujours le même: vos liens ne sont pas en Markdown. La correction est triviale — cinq caractères par lien — et souvent réalisable en quelques minutes. Mais ne vous arrêtez pas là: un bon llms.txt raconte votre site aux machines avec justesse. Il documente les portes d’entrée, expose vos flux les plus frais et formalise vos conventions. C’est une brique clé d’une architecture “machine-first” qui rend vos contenus plus découvrables, citables et utiles dans un web de plus en plus piloté par l’IA.

Commencez par “faire passer le test” — pour la tranquillité et l’automatisation. Continuez par “écrire pour les agents” — pour la valeur durable. Votre prochain utilisateur pourrait très bien être un modèle de langage. Donnez-lui une carte claire. 🧭

Source