Markdown vous freine
(newsletter.bphogan.com)- Markdown, largement utilisé pour rédiger de la documentation de développement, est populaire grâce à sa simplicité et à son accessibilité, mais il montre ses limites pour la documentation technique à grande échelle en raison d’un manque d’expressivité structurelle
- Markdown fonctionne comme un système de types implicite, ce qui empêche toute validation de cohérence ou de schéma, et pose aussi des problèmes de compatibilité entre les différentes variantes de Markdown (flavors)
- Des syntaxes étendues comme MDX augmentent l’expressivité, mais elles accroissent au contraire la complexité à cause d’un manque de portabilité et de standardisation entre les systèmes
- reStructuredText, AsciiDoc, DocBook et DITA offrent une structure explicite et un balisage sémantique (semantic markup) qui renforcent la réutilisabilité et l’interprétation par les machines
- Markdown suffit pour les petits documents, mais la gestion documentaire à grande échelle et multicanal nécessite de passer à des formats structurés
Les limites structurelles de Markdown
- Markdown permet de produire, grâce à une syntaxe simple et lisible par les humains, des documents agréables à consulter sur GitHub ou sur des sites statiques
- Mais il ne décrit pas la signification du contenu, d’où un manque d’informations structurelles compréhensibles par les machines
- Les moteurs de recherche, les LLM, les IDE et les agents IA exploitent la structure sémantique des documents, alors que Markdown ne génère qu’un ensemble limité de balises HTML
- Markdown entraîne aussi des problèmes d’incohérence lors de la réutilisation ou de l’intégration de contenus, à cause des différences de syntaxe selon les plateformes
- Au final, Markdown est un format du plus petit dénominateur commun, peu adapté à la gestion de documents complexes
Le problème du typage implicite de Markdown
- Markdown est un format sans schéma explicite ni définition de types, si bien qu’un même titre ou une même liste peut avoir des significations différentes selon le contexte
- Il existe de nombreuses variantes de Markdown, ce qui provoque des différences de rendu entre outils
- Exemple : certains outils prennent en charge les notes de bas de page, tandis que d’autres les ignorent
- MDX étend l’expressivité en insérant des composants React, mais sa portabilité reste faible à cause des problèmes de compatibilité entre systèmes
- Ces extensions cherchent à compenser les limites de Markdown, mais ne sont en réalité que des solutions de contournement temporaires non standardisées
L’importance du balisage sémantique
- Le balisage sémantique décrit la signification du contenu, et non sa forme
- Exemple : une « étape (step) » et un « élément de liste » peuvent se ressembler visuellement, tout en ayant un sens différent
- HTML5 a renforcé l’expression structurelle en introduisant des balises fondées sur le sens comme
<section>,<article>et<aside> - Principaux avantages du balisage sémantique
- Transformation et réutilisation : un même contenu peut être converti en HTML, PDF, ePub et d’autres formats
- Interprétation par les machines : les LLM ou les agents identifient plus clairement la structure et peuvent fournir des réponses plus précises
- Markdown ne fournit pas ces informations structurelles, ce qui entraîne des pertes d’information lors du post-traitement ou de la conversion
Comparaison des formats alternatifs
- reStructuredText
- Format utilisé dans Sphinx au sein de l’écosystème Python, il exprime la structure sémantique via des directives (directive) et des rôles (role)
- Prend en charge des éléments structurels explicites comme les blocs de code, les notes (
note) et les références croisées (:ref:) - Adapté à la documentation technique à grande échelle, avec génération en HTML et PDF
- AsciiDoc
- Format texte sémantique offrant des attributs (attribute), du contenu conditionnel et la fonction include
- Prend en charge des expressions spécialisées pour la documentation technique comme les encadrés
NOTE,WARNING, les éléments d’interface utilisateur et la notation des raccourcis clavier - Convertible en HTML, PDF, ePub ou DocBook via AsciiDoctor
- DocBook (XML)
- Modèle basé sur XML pour l’édition technique, avec un système de balises porteuses de sens comme
<command>,<note>et<xref> - Inclut les balises nécessaires à la documentation experte : glossaires, index, éléments d’interface utilisateur, noms de fonctions, etc.
- Peut être converti vers de nombreux formats de sortie grâce aux feuilles de style XSLT
- Particulièrement avantageux pour la validation de structures documentaires à grande échelle et la génération d’index
- Modèle basé sur XML pour l’édition technique, avec un système de balises porteuses de sens comme
- DITA (Darwin Information Typing Architecture)
- Structure modulaire basée sur XML utilisée comme standard de documentation technique en entreprise
- Architecture XML orientée sujets, qui définit clairement des structures procédurales comme
<task>et<step> - Utilisée comme standard de gestion documentaire en entreprise pour la réutilisation de contenu (
conref), le filtrage et la publication multicanal - Prend en charge l’automatisation du rendu et des conversions via DITA Open Toolkit
Pourquoi XML reste nécessaire, même s’il semble contraignant
- Markdown est léger, mais c’est une solution provisoire dépourvue de structure, de standard et de cohérence
- Si vous ajoutez de la complexité à Markdown avec MDX, des plugins ou des scripts personnalisés,
adopter directement un format structuré sera plus stable sur le long terme
Alors, que faire ?
- Markdown suffit pour les petits documents comme un README ou une documentation ponctuelle, mais pour une documentation à grande échelle, réutilisable et multicanal, reStructuredText, AsciiDoc, DocBook et DITA sont plus adaptés
- Si vous avez besoin de documents de conception, de documentation développeur, de réutilisation ou de gestion à grande échelle, envisagez les formats dans l’ordre reST/AsciiDoc puis DocBook/DITA
- Il est préférable d’utiliser comme source le format le plus riche structurellement, puis de le convertir en Markdown si nécessaire
- Markdown est utile comme format de sortie, mais l’utiliser comme source of truth rend l’extension structurelle difficile
- L’idéal est de conserver la source dans un format riche en structure sémantique et d’utiliser Markdown pour les sorties downstream
7 commentaires
rst est-il un format basé sur XML ? C’est la première fois que j’entends ça. Le résumé est étrange.
Il semble que le titre ait été rédigé ainsi parce que, dans le résumé, les critères de sélection étaient évoqués en le regroupant avec d'autres formats XML.
Je l'ai corrigé pour qu'il corresponde au texte original.
Si besoin, on peut utiliser du HTML dans Markdown et y greffer Mermaid, ça passe à peu près… mais au-delà, on a l’impression que ça devient du travail sur la documentation pour le travail sur la documentation.
Les humains passent avant l’IA. Ne vole pas ce que j’ai écrit. Et puis quoi encore avec ton baratin sur la sémantique.
Si cela impose d’utiliser une syntaxe particulière, il faut alors aussi assurer un support fluide pour toute une autre courbe d’apprentissage, des outils de parsing dédiés, des visionneuses, des éditeurs, etc. À ce niveau-là, il vaudrait peut-être mieux utiliser simplement Google Docs ou Notion, qui peuvent se connecter sans friction à la plupart des services d’IA.
Commentaires Hacker News
Le cœur de Markdown, c’est sa prise en charge extrêmement large, que les autres langages n’ont pas La plupart des alternatives demandent des outils spécifiques et ne peuvent pas être utilisées dans les environnements où Markdown est déjà pris en charge Même Google Docs prend en charge le collage Markdown via une fonctionnalité cachée Même imparfait, son avantage est qu’on peut l’utiliser « partout » Comme HTML était plus simple que SGML mais est devenu le standard grâce au support des navigateurs, Markdown peut lui aussi évoluer avec le temps Son ambiguïté de standardisation, son manque de fonctionnalités et ses problèmes de compatibilité rappellent la période HTML4 Plutôt qu’un remplacement total, une évolution progressive semble être la voie la plus réaliste
Markdown permet d’inclure des balises HTML n’importe où C’est indiqué explicitement dans la documentation officielle Donc la contrainte évoquée par l’auteur n’existe pas réellement
ou, Markdown perd son intérêt Au final, si la réponse est « il suffit d’utiliser du HTML », alors la raison d’être de Markdown disparaîtÀ l’université, quand j’étudiais la physique, j’écrivais mes articles en LaTeX En chimie, ils utilisaient Word, les standards varient donc selon les disciplines Le numéro de version de TeX exprime son niveau de complétude cible en se rapprochant de π La version actuelle est 3.141592653, maintenue de façon stable depuis 47 ans Voir wiki TeX, explication des versions en π Pour les outils CLI, le format manpage est aussi utile
Markdown ressemble à un produit minimum viable (MVP) C’est facile à apprendre, et ça reste lisible même sans rendu Pour produire des PDF, je suis passé d’AsciiDoc à Typst, qui a résolu des problèmes d’accessibilité Mais aucun langage de balisage n’améliore à lui seul la qualité de l’écriture Ce n’est pas parce qu’on change de stylo que le texte devient meilleur
Le ton de cet article revient à dire que « Markdown freine les progrès des LLM » Mais supposer qu’on peut obtenir automatiquement une richesse sémantique est irréaliste Dans une équipe, personne n’a le temps de faire ce travail, et Markdown suffit largement Comme dans les discussions sur le web sémantique, la vraie question est de savoir qui gère les données
J’écris mon blog avec Org-mode + Emacs J’aime particulièrement la possibilité de relier des blocs de code pour les exécuter dans le document J’ai essayé des plateformes comme Blorgit et lazyblorg, mais comme leur configuration était fastidieuse, j’exporte moi-même en HTML puis j’envoie sur le serveur avec rsync Je déploie ensuite en ajoutant un index via un script Ruby C’est bien plus expressif et naturel que Markdown
Je suis partiellement d’accord avec l’idée que « Markdown manque de structure », mais je regrette cette approche binaire Il aurait d’abord fallu comprendre de quel niveau de structure on avait besoin avant de choisir un format Du coup, je trouve ça à la fois un peu agaçant et difficile à approuver
Présenter DITA comme une alternative à Markdown est une proposition complètement à côté de la plaque DITA est un système XML d’entreprise à grande échelle, dont l’objectif n’a rien à voir avec Markdown Cela n’a de sens que dans des environnements de plus de 5 000 personnes, avec des gammes de produits multilingues Si l’on est dans une situation où Markdown convient, alors DITA ne convient absolument pas Les deux sont une perte de temps
J’utilise Markdown depuis plus de 10 ans et ça fonctionne toujours très bien Les arguments de l’article ne sont pas totalement faux, mais ce ne sont pas des problèmes ressentis par les utilisateurs de Markdown Si besoin, il suffit d’utiliser autre chose Cela dit, le titre était bon, donc j’ai quand même pris 5 minutes pour lire
C’est étrange de citer MyST comme une forme de Markdown, puis de reprendre reStructuredText (rST) comme exemple Le but même de MyST est justement de remplacer rST La syntaxe ressemble à Markdown, mais elle prend aussi en charge la structure sémantique, les directives, les rôles, etc. Il y a aussi une discussion liée dans cette issue Sphinx
On voit beaucoup de textes de ce genre ces temps-ci.
Fichiers texte, Markdown, formats plus structurés
en évoluant ainsi, il n’y a pas de réponse universelle : il faut simplement utiliser le format adapté au bon moment.
Et puis, dès qu’on essaie de tout faire dans un seul fichier, les problèmes apparaissent ; il devient donc inévitable de classer et de structurer selon le sujet.