HTML et Markdown : vérifier la parité avant publication
Une conversion HTML vers Markdown peut perdre une restriction, changer la portée d'une procédure ou casser un lien relatif. Pour une documentation exposée via llms.txt, comparez ces éléments avant publication.
La proposition llms.txt v2 décrit les représentations Markdown et leur découverte par des liens. La fidélité de leur contenu reste à contrôler dans la chaîne de publication.
Une conversion fidèle peut changer la forme, pas la condition
Prenons une documentation fictive dont la page HTML décrit une fonction disponible uniquement avec une version précise de l'API. Le générateur Markdown conserve le nom de la fonction et son exemple, mais perd l'encadré qui indique la version requise. Le texte exporté paraît complet. Un lecteur qui ne reçoit que cette représentation peut pourtant appliquer l'exemple au mauvais environnement.
La parité ne signifie donc pas une égalité caractère par caractère. Retirer la navigation, les boutons de partage ou un bandeau de consentement peut rendre le document plus utile. Retirer une restriction, une unité ou une condition d'accès en change le sens.
| Élément de la page HTML | Différence acceptable à examiner | Différence qui affecte le sens |
|---|---|---|
| Menu du site | Navigation raccourcie | Lien vers la mauvaise version conservé |
| Encadré de prérequis | Présentation simplifiée | Prérequis supprimé |
| Tableau | Syntaxe Markdown différente | Colonne d'unité ou de condition perdue |
| Exemple | Mise en forme adaptée | Paramètre ou valeur modifié |
| Note liée à une phrase | Note déplacée avec son contexte | Note détachée de l'affirmation qu'elle limite |
Cette comparaison porte sur les informations utiles au lecteur. Elle évite un test trompeur qui accepterait un export parce qu'il contient le titre et quelques mots-clés communs.
Vérifier une chaîne de publication avec une seule révision
Choisissez une page qui vient réellement de changer. Identifiez la révision attendue, puis récupérez le HTML et le Markdown servis. Une comparaison avec le fichier source local peut expliquer une erreur, mais le lecteur reçoit la version publiée. Les deux observations sont nécessaires pour localiser la rupture.
Si le HTML contient la nouvelle condition et le Markdown l'ancienne, examinez la génération et la diffusion. Si les deux versions sont anciennes, cherchez plutôt ce qui les empêche de recevoir la modification. Si elles sont actuelles mais contradictoires, le transformateur peut avoir altéré le sens.
La RFC 9111 décrit le fonctionnement des caches HTTP. Elle aide à analyser une représentation encore servie, mais ne dit pas quelle configuration votre hébergement applique. Conservez les en-têtes observés avec le contenu lorsque le diagnostic porte sur le cache.
Tester les liens comme des destinations documentaires
Un lien peut répondre correctement tout en conduisant au mauvais chapitre. Vérifiez son titre, sa version et sa langue. Lorsqu'une URL relative est déplacée dans un fichier Markdown servi ailleurs, examinez ce qu'elle désigne effectivement depuis ce nouvel emplacement.
Pour un petit échantillon de recette, choisissez une page avec tableau, une avec prérequis et une avec liens de version. Cette sélection est une recommandation fondée sur les défauts possibles, pas une preuve de couverture complète du site.
Le résultat attendu est une liste d'écarts expliqués. « Menu absent volontairement » et « restriction disparue » peuvent être détectés par le même outil ; ils ne doivent pas recevoir la même décision. Une recette utile aide à accepter les simplifications et à corriger les pertes de sens.
Publier les représentations comme un ensemble
Une mise à jour peut atteindre la page HTML avant sa représentation Markdown. Un cache peut aussi conserver une ancienne réponse. La RFC 9111 décrit les mécanismes de fraîcheur et de validation HTTP ; leur configuration réelle doit être contrôlée sur votre hébergement.
Notre recommandation est de rattacher les deux représentations à une même révision éditoriale. Après publication, relisez les réponses publiques et conservez leurs empreintes avec l'heure du contrôle. Une empreinte différente est un signal à examiner, pas la preuve automatique d'une divergence de fond.
Si les versions sont désynchronisées, corrigez le déploiement ou retirez temporairement le lien vers la représentation inexacte. Ne changez pas une date pour faire croire que le contenu est à jour.
Consigner les écarts entre les deux représentations
Un compte rendu exploitable indique la page, sa révision, les éléments comparés, les écarts et la personne chargée de les résoudre. Il distingue « non présent », « inaccessible » et « différent ». Aucune de ces situations ne devrait être automatiquement convertie en réussite.
Prenez une page récemment modifiée et rattachez ses deux représentations à la même révision. Pour chaque écart, notez la correction attendue ou la raison de conserver la différence. Une navigation supprimée peut être volontaire ; un prérequis disparu doit être rétabli.
Appliquez les bonnes pratiques llms.txt aux fichiers produits : vérifiez les liens depuis leur URL finale, avec les versions de documentation réellement servies.