Du Markdown pour les agents IA : servir des versions lisibles de vos pages

Quand un agent ouvre une page, l'essentiel de ce qu'il reçoit, c'est de l'emballage : navigation, pied de page, scripts, balises de suivi, bandeaux de témoins, balisage de mise en page. Il doit tout éplucher pour atteindre l'article ou la description de service qu'il était venu chercher. Il y arrive habituellement, avec quelques pertes en chemin : un tableau aplati, un intertitre échappé, un menu pris pour du contenu.

Le Markdown met fin aux devinettes. Il garde tout ce qui porte le sens (intertitres, paragraphes, listes, liens, tableaux) et laisse tomber le reste, dans un format compact que les modèles de langage digèrent bien. text/markdown est même un type de média enregistré (RFC 7763) : serveurs et clients peuvent donc le désigner précisément.

Un mot sur l'enjeu : les agents savent lire un bon HTML, et les versions Markdown ne changeront rien à votre classement. C'est une façon modeste et peu coûteuse d'aider les machines à vous lire plus fidèlement, et on aime bien ce genre de petites victoires.

1. Une adresse parallèle en .md

Chaque page a droit à un jumeau à la même adresse, suivie de .md : /en/agency devient /en/agency.md. La proposition llms.txt suggère précisément cette convention. Elle se teste facilement dans un navigateur, se lie facilement depuis un fichier llms.txt, et se met en cache sans risque, puisqu'il s'agit d'une adresse distincte.

Faites ensuite en sorte qu'on trouve ce jumeau. Ajoutez un lien dans l'en-tête HTML et, si possible, un en-tête HTTP Link à la réponse HTML :

<link rel="alternate" type="text/markdown" href="https://example.com/en/agency.md">

2. La négociation de contenu avec Accept: text/markdown

HTTP a toujours permis à un client d'indiquer ses formats préférés grâce à l'en-tête Accept (RFC 9110). Un agent qui veut du Markdown peut le demander à l'adresse habituelle de la page :

curl -H "Accept: text/markdown" https://locomotive.ca/fr

Le serveur répond avec Content-Type: text/markdown et le contenu en Markdown. Les navigateurs n'y voient que du feu : ils demandent d'abord text/html et continuent donc de recevoir la page telle qu'on l'a conçue. Une règle sensée : ne servir le Markdown que si le client le classe strictement au-dessus du HTML.

Toute réponse d'une adresse négociée, HTML ou Markdown, devrait inclure Vary: Accept. Cet en-tête signale aux caches que la réponse dépend de ce que le client a demandé.

La négociation de contenu cache un piège classique : la mise en cache. La plupart des CDN et des mandataires inverses mettent en cache selon l'adresse. Si un agent demande /en/agency en Markdown et que le cache garde cette réponse, le visiteur suivant risque d'ouvrir son navigateur sur un mur de Markdown brut, là où votre page devrait s'afficher. L'inverse peut aussi se produire.

Vary: Accept est la réponse normalisée, mais chaque CDN l'interprète à sa façon : certains la respectent, d'autres l'ignorent, d'autres encore refusent de mettre en cache toute réponse qui varie. Ne misez pas uniquement sur elle. Des options plus sûres :

• Contourner le cache pour les requêtes Markdown. Ajoutez au CDN une règle qui évite le cache quand l'en-tête Accept contient text/markdown.
• Marquer le Markdown négocié comme privé. Un en-tête Cache-Control: private indique aux caches partagés de ne pas le conserver du tout.
• Mettre en cache normalement les adresses .md. Ce sont des adresses distinctes : aucune collision possible avec le HTML.

Testez après chaque modification de la configuration de votre CDN : demandez une page en Markdown, chargez-la ensuite dans un navigateur, et confirmez que vous recevez bien du HTML.

Convertissez seulement le contenu principal

Générez le Markdown à partir de la zone de contenu principale de la page et laissez le gabarit de côté, pour que menus et pieds de page n'enterrent pas l'essentiel. Un HTML propre et sémantique rend l'étape presque automatique. Si votre CMS stocke du contenu structuré, vous pouvez aussi produire le Markdown directement à partir de celui-ci, une raison de plus de bien choisir votre CMS.

Restez honnête

Le Markdown doit dire ce que dit la page. Des versions lisibles par machine qui s'éloignent de ce que voient les visiteurs minent la confiance et peuvent être assimilées à du camouflage (cloaking).

Renvoyez à l'original

• Ajoutez un court bloc d'en-tête (front matter) avec le titre, la description, l'adresse canonique et la langue.
• Envoyez un en-tête Link: <adresse-de-la-page>; rel="canonical" pour que la page HTML reste la référence.
• Envoyez X-Robots-Tag: noindex avec les réponses Markdown pour que les moteurs de recherche n'indexent pas de doublons.
• Gardez des liens absolus, pour qu'ils fonctionnent encore quand le texte est lu hors contexte.

N'oubliez pas les erreurs

Une page introuvable devrait elle aussi répondre en Markdown, avec le bon code d'état et quelques liens pour aider un agent à retomber sur ses pieds : accueil, plan du site, llms.txt. Même chose pour les redirections : une requête .md redirigée devrait aboutir à une adresse .md.

Comment locomotive.ca s'y prend

Sur notre propre site, chaque page a une version .md et répond à Accept: text/markdown à son adresse habituelle, par exemple locomotive.ca/fr.md. Les pages HTML annoncent leur version Markdown avec une balise <link> et un en-tête Link. Les réponses portent Vary: Accept ; le Markdown négocié est marqué private, tandis que les adresses .md peuvent être mises en cache publiquement. Les réponses Markdown comprennent un bloc d'en-tête, un lien canonique et noindex, et les erreurs 404 reviennent en Markdown avec des liens pour se retrouver. Chaque page se termine par une courte section sur la façon de travailler avec nous, pour qu'un agent ait toujours le contexte nécessaire. On raconte tout le projet dans comment nous avons préparé locomotive.ca pour les assistants IA.

Commencez par les adresses .md : ce sont les plus simples à bâtir, à tester et à mettre en cache. Ajoutez la négociation de contenu une fois vos règles de cache en place, puis mentionnez les versions Markdown dans votre fichier llms.txt. Jumelez le tout à des données structurées, et les machines obtiennent à la fois le texte lisible et les faits explicites.