Pourquoi je préfère le rST à Markdown

• Le reStructured Text (rST) de Sphinx est plus difficile à apprendre que Markdown, mais il permet de contrôler plus finement la structure et les formats de sortie pour des documents de grande ampleur comme des livres
• Markdown ressemble davantage à une notation légère pour HTML, tandis que le rST s’appuie sur un arbre de document abstrait permettant d’ajouter de nouveaux objets documentaires en combinant directives, nœuds et moteurs de rendu
• Sphinx transforme le doctree avant le rendu, ce qui permet de gérer dans le système documentaire des tâches comme les références croisées, les traitements spécifiques à chaque format de sortie ou les transformations à une étape précise de la build
• Dans Logic for Programmers, des exercices et leurs corrigés sont rédigés à proximité dans la source, puis une extension personnalisée modifie leur position et leur affichage dans les sorties EPUB et LaTeX
• Markdown simple manque d’une syntaxe d’extension unifiée et d’un support natif des transformations avant rendu ; plus un générateur documentaire contourne cela via un prétraitement séparé, plus il perd en support outillage et en extensibilité

---

Pourquoi j’ai choisi le rST

• La nouvelle version de Logic for Programmers est le deuxième livre écrit avec Sphinx ; le précédent, la nouvelle version de Learn TLA+, utilisait déjà Sphinx
• Sphinx utilise reStructured Text, et le rST a une courbe d’apprentissage plus raide que Markdown
• Après avoir écrit plusieurs livres en Markdown, j’ai basculé vers le rST parce que j’avais besoin de meilleurs outils
• Le rST est indépendant de Sphinx, mais en pratique on l’utilise souvent à cause de Sphinx, donc les deux sont abordés ensemble

Différence de structure entre Markdown et rST

• La plus grande différence est que Markdown se rapproche d’une notation légère pour HTML, alors que le rST est une notation intermédiaire conçue pour produire un arbre de document abstrait
• La syntaxe d’image de Markdown peut être convertie en HTML comme <img alt="alttext" src="example.jpg"/> par une transformation simple
  • Les moteurs Markdown modernes passent eux aussi souvent par une représentation intermédiaire, mais leur nature de base reste proche d’une notation HTML légère
• En rST, une image s’exprime avec la directive .. image::
  • Sphinx cherche le gestionnaire de directive enregistré et exécute ImageDirective.run
  • Le résultat de l’exécution est un objet nœud comme image_node contenant un champ alt
  • Une fois le traitement complet du doctree terminé, le HTML Writer cherche la fonction de rendu de image_node et produit la balise HTML
• L’approche rST est plus complexe à implémenter et sa syntaxe est plus verbeuse que Markdown, mais les images y sont traitées via le même mécanisme d’extension que les autres directives

Comment ajouter de nouveaux objets documentaires

• Avec rST/Sphinx, on peut ajouter de nouveaux objets textuels via des extensions
• Par exemple, si l’on veut produire <figure> et <figcaption> au lieu de <image>, le Markdown de base oblige à insérer directement du HTML
• Avec Sphinx, cela se fait en enregistrant une nouvelle directive figure
  • FigureDirective peut hériter de ImageDirective pour réutiliser l’essentiel du traitement des images
• Le schéma enregistrement de directive, création de nœud, puis enregistrement d’un moteur de rendu par builder s’applique de la même manière à toutes les extensions

Transformations du doctree avant rendu

• Sphinx peut effectuer des transformations du doctree avant le rendu
• Les références croisées entre documents sont aussi gérées ainsi
  • Si un document contient l’ancre foo et qu’un autre contient :ref:\image <foo>``, Sphinx insère la bonne URL lors d’une phase de post-traitement
• Le code de transformation est traité comme une fonctionnalité de premier ordre du processus de build
  • On peut appliquer une transformation uniquement à la sortie HTML
  • On peut exécuter une transformation à une étape précise de la build
  • On peut aussi supprimer des transformations intégrées qu’on ne veut pas exécuter
• Tous les documents n’ont pas besoin d’une telle puissance ; Markdown reste largement utilisé parce qu’il est léger et portable

Exemple d’extension pour exercices et corrigés

• Logic for Programmers est un livre proche des mathématiques, il a donc besoin d’exercices pour les lecteurs
• Lors de la rédaction, il est plus simple de garder les exercices et leurs corrigés proches dans le document, mais pour le lecteur les corrigés doivent apparaître à la fin du livre
• Les exigences différaient selon le format de sortie
  • Il fallait lier chaque exercice à son corrigé
  • En PDF, il fallait aussi des renvois de page pour tenir compte de l’impression
  • Le rendu devait différer entre les sorties LaTeX/PDF et EPUB
• Pour cela, une extension Sphinx personnalisée a été écrite pour gérer exercise, solution et solutionlist
• En sortie HTML de débogage, les exercices et corrigés sont rendus inline
• Pour la génération EPUB et LaTeX, une transformation est exécutée après la construction du doctree complet
  • Tous les solution_node placés à l’origine sont déplacés sous solutionlist
  • Un nœud de référence vers le nouvel emplacement du corrigé est ajouté à chaque exercice
  • Un nœud de référence de retour vers l’exercice d’origine est ajouté à chaque corrigé
• Le builder LaTeX entoure exercices et corrigés avec l’answers environment
• Le builder EPUB rend les corrigés sous forme de popup footnote
• Cette structure est aussi utile pour créer un extrait gratuit du livre
  • À la fin de l’extrait gratuit, on n’inclut que les corrigés des parties présentes dans l’extrait, pas ceux du livre entier

Préférences de syntaxe et alternatives

• L’objection la plus fréquente contre le rST est que sa syntaxe est laide
• Refuser d’utiliser un outil parce qu’on le trouve désagréable à regarder est un choix tout à fait défendable ; on peut voir de la même manière les difficultés à accepter Lisp comme une question de goût
• Parmi les alternatives, on trouve asciidoc, MyST, Typst, Pollen, pandoc-extended markdown
• L’idée centrale n’est pas que Sphinx/rST soit exceptionnellement bon pour la documentation à grande échelle, mais que le Markdown simple soit exceptionnellement mal adapté à ce type de documentation

Limites des générateurs basés sur Markdown

• Le Markdown simple n’a ni syntaxe d’extension unifiée ni support natif des transformations avant rendu
• Beaucoup de générateurs documentaires basés sur Markdown ajoutent leur propre étape de prétraitement pour prendre en charge de nouveaux cas d’usage
• Cette approche fonctionne généralement, mais le traitement ne se fait pas dans Markdown lui-même : c’est un contournement autour de Markdown
• En conséquence, la puissance fonctionnelle reste limitée et les outils pour programmeurs comprennent difficilement ces variantes
  • Il existe des LSP et treesitter pour Markdown et rST, mais il est difficile d’attendre le même niveau d’outillage pour gitbook-markdown, md-markdown ou leanpub-markdown
• La syntaxe peu élégante du rST peut au contraire devenir un avantage, car son arbre syntaxique est plus riche
  • On peut écrire une requête treesitter qui ne modifie que le corps d’une directive todo donnée
  • C’est possible parce que l’arbre syntaxique du rST est plus riche que celui de Markdown

Mise à jour de Logic for Programmers

• Logic for Programmers est un livre sur la manière dont la logique formelle peut être utile dans l’ingénierie logicielle au quotidien
• Le livre commence par un aperçu des bases mathématiques, puis enchaîne sur huit applications comme le property-based testing, les contraintes de base de données ou les tables de décision
• Il est encore en phase alpha, mais il compte déjà 20 000 mots et l’auteur recueille des retours de lecteurs

[GN⁺]

Avis de Hacker News

• Si l’on me demande : « allez-vous vraiment renoncer à utiliser un bon outil parce qu’il vous donne envie de vomir rien qu’en le regardant ? », je répondrai oui. Le principal atout de Markdown, c’est qu’il est facile à lire, et le deuxième, qu’il est facile à écrire.
  La facilité de parsing ou d’extension importe assez peu. Indépendamment de la question de savoir si Markdown est le meilleur choix pour écrire un livre, c’est le meilleur outil pour rédiger rapidement du texte mis en forme d’une manière lisible même par des personnes qui ne connaissent pas bien la syntaxe. Je n’essaie pas d’écrire un livre ; j’ai seulement besoin de prendre des notes, de produire rapidement de la documentation ou d’écrire des commentaires. Et si je devais écrire un livre, j’utiliserais LaTeX avant RST.

  • Quand Markdown a commencé à décoller chez les développeurs, cela semblait être un choix assez étrange. À l’époque déjà, il existait beaucoup de meilleures options pour transformer du texte brut en documents mis en forme, mais les développeurs construisaient autour de Markdown des CMS, des applications de productivité, des outils de gestion documentaire et même des plugins.
    Mais en l’utilisant dans de vraies applications, je me suis rendu compte que le cœur de Markdown n’était pas là. Son objectif est de ne fournir qu’un minimum de mise en forme, afin que le texte brut se lise aussi naturellement que sa version rendue en HTML. L’ensemble des formats pris en charge est volontairement restreint, ce qui permet de le garder en tête et de l’utiliser sans barre d’outils. C’est adapté aux champs de commentaire, au chat, aux messages de commit, et peut-être aux billets de blog, mais pas à la rédaction de documentation produit de niveau entreprise. Aujourd’hui, on utilise Markdown même dans des endroits où il ne sera pas rendu en HTML, parce qu’il est agréable à lire tel quel, et j’aimerais que HN le prenne aussi en charge.
  • J’ai écrit un livre en Markdown et je n’ai pas eu de problème particulier. C’était un roman, pas de la documentation technique, mais rien que je n’aie pu résoudre avec un peu de HTML occasionnel dans le Markdown.
    J’ai aussi produit pas mal de documentation technique en Markdown, et avec les extensions Pandochttps://pandoc.org/MANUAL.html, on peut inclure à peu près toute la mise en forme nécessaire, y compris des formules complexes et des blocs de code avec coloration syntaxique. Ce Markdown peut être converti en HTML, documents Word, ePub, PDF, etc. Il faudrait une raison vraiment très convaincante pour sortir autre chose que Markdown.
  • Je pense faire partie à peu près des 10 % les plus avancés parmi les utilisateurs de TeX, mais j’ai du mal à voir un grand espace pour un autre langage de composition entre Markdown et TeX. Markdown est simple mais limité, tandis que TeX est un peu difficile, mais en pratique infiniment flexible.
    Le plus gros problème que j’ai vu avec TeX n’est pas le langage, mais les gens. Les gens écrivent souvent du TeX spaghetti dans un style épouvantable. Mais si on l’aborde avec l’idée que « les documents sont du code », on obtient des résultats assez propres. Le deuxième plus gros problème est l’absence d’un bon compilateur TeX → HTML.
  • Dire « si j’écrivais un livre, j’utiliserais LaTeX » me semble être un choix horrible pour la phase d’écriture et de structuration. Je préférerais écrire en Markdown sans me soucier de la composition, puis convertir en LaTeX seulement au moment de la publication.
    Je ne maîtrise pas LaTeX, mais lorsque j’ai essayé de l’apprendre, j’ai eu l’impression d’apprendre la langue d’une civilisation extraterrestre insectoïde. Ce n’était absolument pas intuitif, et à moins de copier ce que quelqu’un d’autre avait déjà fait pour n’y insérer que mon propre texte, il était presque impossible de faire quoi que ce soit de nouveau. Dans mon souvenir, il n’y avait pas non plus de prise en charge Unicode de première classe.
  • J’ai du mal à accepter l’idée que Markdown serait « le meilleur outil pour rédiger rapidement du texte mis en forme d’une manière lisible même par des personnes qui ne connaissent pas bien la syntaxe ». Même en ne regardant que les bases, ce n’est pas le meilleur.
    Utiliser des astérisques ou des underscores pour l’italique demande aussi de l’habitude, alors qu’il existe des formes bien plus intuitives, comme /italic slashes/. Dès qu’on sort des bases, les tableaux, les métadonnées et les tags masquent le texte, ce qui les rend difficiles à écrire et à lire sans outil adapté. Si l’extension est facile, on peut aussi corriger ce genre de problèmes de base ; l’extensibilité est donc également pertinente.

• J’ai travaillé environ 12 ans comme rédacteur technique et, au début de ma carrière, j’ai migré la documentation d’une startup de Word vers Sphinx. J’ai ensuite travaillé sur le CMS/la plateforme propriétaire de documentation développeur de Google, sur des sites basés sur Eleventy, et ces deux dernières années de nouveau sur un site basé sur Sphinx, pigweed.dev. J’ai aussi travaillé pour une startup utilisant readme.com et un peu touché à Docusaurus, Astro et Hugo
  reStructuredText seul peut être rugueux, mais reST associé à Sphinx est excellent. Les forces de Sphinx dépassent de très loin les faiblesses de reST. Pour un gros site de documentation professionnelle de plus de 100 pages et avec plus de 10 contributeurs, je suis assez fermement convaincu que Sphinx est, sur le long terme, le choix le plus responsable. Par exemple, chez Pigweed, il suffisait d’écrire :bug:\59385981`` pour que cela devienne un lien vers https://pwbug.dev/59385981, et si nous devions ensuite migrer en masse les liens de bugs, ce serait facile. Les liens internes sont également garantis comme toujours résolus, et un lien vers un emplacement inexistant produit un avertissement ou une erreur. J’ai déjà écrit sur https://technicalwriting.dev/src/link-text-automation.html qu’il est étrange que ce ne soit pas la norme pour les sites de documentation. Sphinx dispose aussi d’API d’extension et de thèmes bien définies, et son écosystème sur PyPI est assez vaste. Ces temps-ci, j’appelle Sphinx le géant endormi des systèmes de documentation ; avec un peu d’effort collectif, il pourrait devenir bien plus impressionnant

  • Ce point est vraiment important. Beaucoup trop de CMS ou de générateurs de sites statiques obligent à saisir directement l’URL finale quand on écrit
    Si le slug change ou si l’on réorganise la structure du site, il faut faire un rechercher-remplacer sur tout le site. Les générateurs de sites statiques pourraient permettre de faire des liens comme [Hello](../hello.md) et les résoudre au moment du build, mais beaucoup d’outils que j’ai utilisés ou examinés vous font saisir directement [Hello](/why/hello/). Cette fonctionnalité semble diviser. Même quand j’en ai parlé à des membres d’une équipe de générateur de site statique, on m’a répondu « pourquoi voudrais-tu ça ? », et mes explications ne sont pas passées. Je ne sais pas s’il faut avoir vécu le problème pour comprendre la valeur de la solution, ou si les gens sont habitués à écrire une fois sans maintenir pendant plus de 10 ans, mais j’aimerais que ce soit plus largement pris en charge
  • Sphinx est formidable, mais gravement sous-estimé. À ma connaissance, Sphinx est le seul framework de documentation structurellement solide, extensible et largement utilisé
    Son écosystème de plugins est excellent et donne un levier énorme pour améliorer la documentation d’une équipe et d’un projet. Je n’aime pas reStructuredText en soi, mais aujourd’hui, grâce à MyST-Parser, la plupart des choses pour lesquelles Sphinx était auparavant fortement lié à RST peuvent aussi être faites en Markdown : https://github.com/executablebooks/MyST-Parser
  • Personnaliser des éléments communs à tout le site était aussi très simple avec Markdown+Pandoc. Remplacer une balise image contenant un lien YouTube par une balise vidéo et une miniature avec texte alternatif, ou connecter des balises image de fichiers vidéo locaux à ffmpeg pour optimiser et redimensionner les vidéos, se faisait en quelques lignes de code
  • Je ne connaissais pas Sphinx avant de lire ce commentaire. J’écris de la documentation technique en parallèle de mon travail de développement depuis plus de 20 ans, et jusque-là j’étais plutôt du côté de TeX et de XSL personnalisé
    Je viens de migrer vers Sphinx un livre de plus de 200 pages qui décrit un langage interne, une VM et une couche d’abstraction, et c’est vraiment un système qui change la vie. J’aimerais que la documentation de Sphinx elle-même ait une barrière d’entrée plus basse ou plus d’exemples, mais pour l’instant je suis clairement en pleine lune de miel. Mes principaux centres d’intérêt sont la création de beaux livres PDF, et un système capable de découper le livre en pages man compatibles POSIX, par chapitre et par section
  • Si l’on veut que Sphinx rencontre un grand succès auprès du grand public, la priorité numéro un est de disposer de thèmes beaux et de grande qualité
    L’esthétique compte pas mal quand on choisit un générateur de site. Hugo et Gatsby ont d’excellents thèmes par défaut, et il m’est arrivé de les choisir pour un projet uniquement pour cette raison. Les collections de thèmes Sphinx https://sphinx-themes.org/ et https://sphinxthemes.com/#featured-themes sont globalement fades. Le thème Sphinx RTD standard https://sphinx-rtd-theme.readthedocs.io/en/stable/ paraît vieilli si on le compare à la documentation Apple https://developer.apple.com/documentation/swift/array ou à Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default

• Je pense que la phrase « Markdown est une représentation légère de HTML » est le plus gros problème de ce texte. C’est clairement inexact
  Markdown a été conçu comme un outil pour convertir des conventions de mise en forme textuelle qui étaient de facto utilisées comme un standard dans les e-mails et les messages Usenet au début des années 1990. À cause de la contrainte du 7-bit ASCII, on marquait les mises en forme comme l’emphase ou les titres avec des caractères spéciaux, et HTML avait aussi beaucoup de points communs avec ces conventions anonymes. C’est pourquoi John Gruber a écrit en 2004 le script de base https://daringfireball.net/projects/markdown/ qui les transformait en HTML, mais il ne s’attendait sans doute pas à ce que cela devienne un standard réel aussi universel

  • La première phrase de ce lien dit justement : « Markdown is a text-to-HTML conversion tool for web writers. »
    Gruber n’a pas simplement pris le standard de facto d’Usenet pour en faire un convertisseur HTML ; il a conçu son propre balisage en empruntant à Usenet et à d’autres conventions. La section « Acknowledgements » en bas du lien le montre aussi. Markdown était dès le départ destiné à être une syntaxe de balisage pour les CMS web, et dire que c’est une représentation légère de HTML est correct. Le point central était que chaque partie de la syntaxe produise du HTML correspondant directement
  • Je ne suis pas d’accord. Markdown a toujours été lié à HTML, au point que les parseurs Markdown prennent en charge le mélange de balises HTML réelles
    Le fait qu’il ait été inspiré par les conventions des e-mails ne rend pas moins juste l’affirmation selon laquelle « Markdown est une représentation légère de HTML »
  • J’aimerais qu’on arrête ce genre de querelles sémantiques. Cela rend les discussions ennuyeuses et va aussi à l’encontre des guidelines de HN
    Il y a une règle qui dit de répondre à l’interprétation la plus plausible et la plus forte de ce que l’autre personne a dit, au lieu de choisir une interprétation faible facile à critiquer. Il y a aussi une règle qui dit de ne pas sélectionner la phrase la plus provocatrice d’un article pour s’en plaindre, mais de répondre aux parties intéressantes : https://news.ycombinator.com/newsguidelines.html
    Si vous n’êtes pas d’accord avec le cœur du texte, dites que vous préférez Markdown à rST et expliquez pourquoi. Se battre sur une seule phrase pour déterminer ce qu’est exactement Markdown est idiot
  • Markdown lui-même est distinct de la mise en forme des e-mails et d’Usenet. Markdown était une syntaxe spécifique, mal définie, qui s’est ensuite élargie en plusieurs familles de syntaxes globalement assez similaires
    Il s’est certes inspiré de conventions comme celles des e-mails ou d’Usenet, dont certaines existaient même avant l’informatique. Par exemple, il me semble avoir vu dans de vieux documents tapés à la machine des astérisques utilisés comme de l’italique. Mais Markdown est fortement lié à HTML, sa syntaxe est très contrainte par HTML, et les tentatives de l’en séparer sont généralement vouées à l’échec
  • Les deux ont raison. L’implémentation originale était un sur-ensemble de HTML. On utilisait la syntaxe légère pour les choses courantes, et HTML pour le reste

• Je pense que le cœur de Markdown est de permettre de faire les choses simples plus vite qu’en HTML brut, tout en permettant, si nécessaire, de mélanger du HTML brut
  Dans les projets où j’avais besoin de la puissance de RST plutôt que de Markdown, il était plus pratique d’écrire directement en HTML

  • Quand l’auteur écrit, en substance, « on peut étendre Sphinx pour créer de nouveaux objets textuels ; avec Markdown de base, il faut insérer directement du HTML », je me demande quel est le problème à simplement utiliser HTML quand on a besoin de ce genre de fonction. Je ne comprends pas pourquoi ajouter une couche de plus

• En construisant un système documentaire d’une complexité similaire, j’ai envisagé RST parce que j’avais vraiment besoin d’un balisage doté d’une sémantique claire, en stockant la structure des fichiers RST dans une base de données et en mélangeant les résultats de la base avec le contenu
  Je me suis heurté à deux problèmes. D’abord, les outils RST n’ont pas d’unparser capable de réémettre du RST. Je voulais fusionner plusieurs fichiers RST et d’autres sources pour générer automatiquement des fichiers RST et les manipuler via une API documentaire, mais ce n’était pas pris en charge. Ensuite, les outils RST s’attendent à un ensemble de blocs défini pour un document donné. Si les blocs étaient représentés de manière générique, il serait possible de créer des outils qui transforment un document sans connaître les définitions internes des blocs, mais ce n’est pas le cas. C’est un problème d’outillage plus que de RST lui-même, mais chaque fois qu’il faut décortiquer le code jusqu’au fond, on finit par penser à d’autres systèmes de balisage, comme ceux basés sur HTML

  • Au lieu de HTML, on peut utiliser XML pour écrire des documents structurés. XML permet de définir les tags personnalisés nécessaires et, si on le souhaite, de faire une validation par schéma
    L’avantage de cette approche est de contrôler entièrement le schéma d’entrée et la sortie ; l’inconvénient est que la syntaxe est beaucoup plus bruyante que Markdown ou RST, et qu’il faut des scripts pour parser et convertir vers le format de sortie voulu
  • En Python, rST n’est qu’un des nombreux formats d’entrée pris en charge par docutils : https://docutils.sourceforge.io/README.html#purpose
    Tout l’objectif de docutils est de parser des formats et de les convertir en API : https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
  • rST et AsciiDoc semblent à peu près similaires sur le plan des fonctionnalités. Je me demande si leurs faiblesses et fonctionnalités manquantes sont elles aussi à peu près similaires
  • J’ai été committer sur docutils, l’outil principal de rST. L’une des raisons pour lesquelles j’ai migré mes outils vers Markdown, c’est que travailler avec docutils était trop pénible. Rien que son refus de migrer vers un endroit comme GitHub montre à quel point il est peu accueillant de collaborer avec eux
  • Je n’ai pas d’ordinateur sous la main pour tester, mais j’ai l’impression qu’on peut faire ce qu’on veut avec la directive include

• Il y a quelques années, j’avais résumé le sous-ensemble de reStructuredText qui valait la peine d’être mémorisé : https://simonwillison.net/2018/Aug/25/restructuredtext/
  Dans mes projets récents, j’ai commencé à utiliser MyST : il fournit les fonctionnalités de références et de tables des matières que j’appréciais dans reStructuredText, tout en permettant aux contributeurs d’utiliser une syntaxe Markdown plus facile à écrire.

  • L’avantage est important pour les liens, en particulier les liens externes. Sur un site de documentation, on peut référencer le même lien externe à plusieurs endroits, et quand il change, on veut ne le mettre à jour qu’une seule fois.
    Ce qui change vraiment la donne, ce sont les liens internes avec rST+Sphinx et les directives :ref:, :doc:. Quand on référence une ancre ou un lien vers un document dans le même contenu, on n’a pas besoin de saisir soi-même l’en-tête, et on évite que l’en-tête saisi à la main finisse par devenir obsolète : https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
    C’est l’une des fonctionnalités qui me manquent le plus quand j’écris en rST.

• Sans vouloir détourner la discussion sur ReStructuredText, si vous cherchez un langage de balisage qui offre plus que Markdown, je recommanderais de regarder AsciiDoc plutôt que ReStructuredText. J’ai rédigé de la documentation technique pendant des années avec les trois, et je trouve qu’AsciiDoc est meilleur que ReStructuredText et Markdown.
  Par exemple, la prise en charge des tableaux dans Markdown et ReStructuredText est très fastidieuse. Le formatage des tableaux en AsciiDoc est facile à lire, à écrire et à maintenir, et il est plus puissant : il prend en charge les en-têtes, les légendes, les tailles personnalisées de tableaux et de lignes, ainsi que les mises en forme complexes à l’intérieur des tableaux. C’est un format standard unique, sans les multiples dialectes de Markdown ; sa syntaxe est concise et lisible, et sa courbe d’apprentissage est plus douce que celle de ReStructuredText. Les options de stylisation de sortie sont meilleures, la chaîne d’outils est supérieure, et les fonctionnalités de documentation intégrées sont riches, ce qui réduit le besoin de dépendre de plugins tiers. AsciiDoc a été conçu dès le départ pour la documentation technique, alors que les deux autres ont plutôt été adaptés à ce rôle.

• Si l’on met joliment en forme un document Markdown d’environ 5 à 10 pages, rendu lui-même depuis un template Jinja plus dynamique, on démarre de façon assez satisfaisante. Il y a aussi un processus de build pour la documentation automatique, et c’est trop gros pour un simple README GitHub. Mais c’est là que la douleur commence.
  La documentation via les pages de projet GitHub ne convient pas vraiment, et on se demande s’il faut un fichier .nojekyl, ou si la branche gh-pages est encore nécessaire. On ne sait pas si c’est une erreur de configuration du dépôt ou si les changements ne sont pas pris en compte, et après quelques heures à essayer GitHub Actions, cela devient irrationnel. En revenant voir Read the Docs, on a l’impression qu’il veut Sphinx, donc on assemble Markdown et Sphinx ; le build passe, mais après le déploiement la largeur de page est cassée, sans reproduction en local, probablement à cause de l’insertion de publicités sur l’offre communautaire. Cela fonctionne bien pour beaucoup de projets, et je l’ai déjà fait moi-même, mais avant que ça marche, c’est incroyablement rempli de petits détails pénibles. Au final, Markdown contre RST n’est même pas le sujet : l’essentiel est de trouver une combinaison qui convienne bien aux projets de documentation de taille moyenne et à l’hébergement statique.

  • Je me demande si vous avez regardé mdBook. Je ne l’ai pas utilisé moi-même, mais j’ai apprécié la documentation de plusieurs projets qui l’utilisent, et cela semble plutôt adapté dès qu’on dépasse le simple fichier README.
    Les instructions de déploiement automatique sont également bien faites : https://github.com/rust-lang/mdBook

• Il me semble qu’on passe à côté du fait que l’auteur parle dans le contexte de la composition typographique de son propre livre. Il ne prétend pas que rST est généralement meilleur que Markdown.
  Dans le cas général, la simplicité de Markdown explique son adoption large, mais ce n’est pas ce dont parle l’auteur.

• C’est amusant de voir des réactions comme si reST avait été créé comme concurrent de Markdown. En réalité, c’est presque l’inverse. reST est une évolution de StructuredText datant de 2002, tandis que Markdown a été publié pour la première fois en 2004.
  Leurs objectifs sont très similaires, et pour le texte le plus basique, les deux se lisent et s’écrivent comme du texte brut. À cette époque, tout le monde a commencé à vouloir ce genre de chose, et plusieurs formats sont apparus. Je ne pense pas que Markdown ait gagné parce qu’il serait « plus simple » ou « plus lisible ». Pour les contenus qui s’expriment facilement en ASCII pur et avec des espaces, ils sont globalement interchangeables. Qui dirait que le document reST de l’exemple est un texte ésotérique illisible sans parseur ? Je ne vois pas vraiment en quoi une variante de Markdown serait meilleure que cela ; c’est surtout un hasard historique qui a fait prévaloir l’un des deux, alors que les deux remplissent suffisamment bien leur objectif central.

  • Comme l’exemple est très simple, Markdown comme reST peuvent le gérer facilement.
    reST fournit beaucoup de fonctionnalités de mise en forme supplémentaires utiles quand on en a besoin, mais superflues quand ce n’est pas le cas. J’ai commencé à utiliser GitHub-flavored Markdown vers 2010, quand je me suis inscrit sur GitHub, et j’ai aussi utilisé quelques fois reStructuredText à cause de la documentation Python. Ce dernier avait une courbe d’apprentissage bien plus raide, et je n’ai plus eu de raison de l’utiliser ensuite.
  • Est-ce illisible ? Non. Est-ce frustrant à saisir ? Oui. Les titres soulignés sont pénibles à éditer, et même s’il n’est pas nécessaire d’aligner exactement la longueur, on ressent une pression pour le faire.
    Les doubles backticks sont aussi une syntaxe disproportionnellement agaçante par rapport au temps qu’ils prennent réellement.