John Mueller : vos pages Markdown ne sont pas forcément visibles par Google

John Mueller, porte-parole de Google Search, vient de clarifier un point technique qui risque de surprendre pas mal de développeurs : un fichier Markdown brut (.md) n’est pas une page web aux yeux de Google. Si votre contenu reste au format .md sans conversion HTML, le moteur de recherche ne le traitera pas comme une page classique. La déclaration arrive alors que de nombreux sites techniques publient directement en Markdown, sans toujours vérifier le rendu final.

Un fichier texte n’est pas une page indexable

Selon John Mueller, le problème est simple : « Les pages .md ? Ce sont juste des fichiers texte. » Si votre système de gestion de contenu ou votre générateur de site statique ne transforme pas ce Markdown en HTML correct, Google ne le considère pas comme une page web standard. Concrètement, cela signifie pas de balises <title>, pas de structure <h1>/<h2> reconnue, pas de métadonnées exploitables. Le fichier peut techniquement être crawlé, mais il ne se comportera pas comme prévu dans les résultats de recherche.

Pour l’utilisateur qui publie en Markdown via GitHub Pages, Notion ou certains CMS headless, le risque est réel. Si la plateforme n’assure pas la conversion en HTML propre côté serveur, le contenu reste invisible ou mal interprété par les robots. Mueller précise que la conversion HTML vers Markdown dispose d’outils mieux maintenus, suggérant que le flux inverse (Markdown → HTML) nécessite une attention particulière.

Ce que ça change pour les sites techniques et les docs

Beaucoup de documentations techniques, de blogs développeurs et de wikis internes utilisent Markdown pour sa simplicité. Le format est léger, facile à versionner avec Git, et permet d’écrire vite. Sauf que si votre générateur de site (Jekyll, Hugo, MkDocs) ne produit pas de HTML correct ou si vous exposez directement les .md bruts, vous perdez en visibilité SEO.

Un exemple concret : un dépôt GitHub avec des fichiers README.md ou des docs en .md. Si ces fichiers sont affichés via l’interface GitHub, pas de souci, GitHub les convertit. Mais si vous les servez directement depuis un serveur web sans traitement, Google les voit comme du texte brut. Résultat : aucune mise en forme, aucune hiérarchie reconnue, et un positionnement aléatoire dans les résultats.

Vérifier le rendu HTML avant de publier

La recommandation de Mueller est claire : assurez-vous que votre Markdown est bien converti en HTML avant d’atteindre le navigateur. Inspectez le code source de vos pages publiées. Si vous voyez des <h1>, <p>, <strong> et autres balises HTML, tout va bien. Si vous voyez du texte brut avec des #, ** ou -, c’est que la conversion n’a pas eu lieu.

Pour vérifier rapidement : ouvrez une de vos pages en .md dans un navigateur, faites clic droit → « Afficher le code source ». Si le contenu ressemble à du Markdown brut, vous avez un problème. La plupart des générateurs de sites statiques (Gatsby, Next.js avec plugins Markdown, Astro) gèrent cette conversion automatiquement, mais certains setups custom ou certains hébergements mal configurés laissent passer les fichiers bruts.

Ce rappel intervient au moment où de plus en plus d’équipes adoptent des workflows « docs as code », où le Markdown sert de source unique pour la documentation. Une bonne pratique consiste à tester le rendu HTML en local avant de déployer, et à vérifier régulièrement que les URLs exposées servent bien du HTML, pas du texte brut.

Les performances des outils IA mentionnés peuvent varier selon les usages et évoluent rapidement. Vérifiez les tarifs et conditions directement auprès des éditeurs.