mdBook — un outil en ligne de commande pour créer des livres en Markdown

• Quand il faut diffuser de la documentation et des tutoriels sous forme de livre, mdBook 0.5.3 combine une rédaction basée sur Markdown et des sorties navigables
• Grâce à la syntaxe Markdown légère et à la recherche intégrée, les auteurs peuvent se concentrer davantage sur le contenu que sur la mise en forme
• Les blocs de code avec coloration syntaxique et les fichiers de thème permettent d’adapter la lisibilité et le format de sortie nécessaires à la documentation technique
• Les préprocesseurs et les backends offrent des points d’extension pour la syntaxe personnalisée, la modification du contenu et le rendu vers plusieurs formats de sortie
• Utilisé par des projets Rust et par le livre The Rust Programming Language, l’outil est fortement lié à l’écosystème de documentation Rust

---

Fonctionnalités de base pour créer un livre en Markdown

• mdBook est un outil en ligne de commande destiné à créer des livres en Markdown
• Il convient à la création de contenus propres et faciles à parcourir, comme de la documentation produit, de la documentation d’API, des tutoriels ou des supports de cours
• Il fournit aussi des fonctionnalités qui améliorent l’expérience d’écriture et de lecture
  • La syntaxe Markdown légère permet de se concentrer sur le contenu
  • Prise en charge de la recherche intégrée dans le livre
  • Application d’une coloration syntaxique en couleur aux blocs de code dans plusieurs langages
  • Possibilité de personnaliser le format de sortie avec des fichiers de thème

Extensions et lien avec l’écosystème Rust

• Les préprocesseurs peuvent prendre en charge l’extension de la syntaxe personnalisée et la modification du contenu
• Les backends permettent le rendu vers plusieurs formats de sortie
• mdBook est écrit en Rust pour la rapidité, la sûreté et la simplicité
• Il prend en charge les tests automatiques des exemples de code Rust

Cas d’usage réels et mode de contribution

• La documentation de mdBook elle-même est un exemple de résultat généré avec mdBook
• Le projet du langage de programmation Rust utilise mdBook, et le livre The Rust Programming Language en est également un cas d’usage
• mdBook est un projet gratuit et open source
  • Le code source est disponible sur GitHub
  • Les issues et demandes de fonctionnalités peuvent être déposées sur le GitHub issue tracker
  • Pour contribuer, vous pouvez lire le guide CONTRIBUTING et ouvrir une pull request
• Le code source et la documentation de mdBook sont distribués sous licence Mozilla Public License v2.0

[GN⁺]

Avis sur Hacker News

• Il me semble que cette plateforme utilise des bibliothèques hébergées sur CDN sans les bundler ni les vendoriser. Les utilisateurs sont donc exposés non seulement aux pannes du CDN, mais aussi aux données collectées par ce serveur
  Ce qui est encore plus regrettable, c’est que la manière d’utiliser Highlight.js et MathJax côté frontend est très peu efficace. Tous les clients doivent parser et rendre eux-mêmes la syntaxe et le LaTeX, et répètent le même travail à chaque visite pour obtenir le même résultat. La coloration syntaxique peut être traitée au moment du build, et il n’y a quasiment aucune raison d’avoir besoin de JavaScript pour cela

  • MathJax semble être hébergé sur un CDN, tandis que le CSS et les autres fichiers JS sont placés à côté du fichier HTML
    Comme la prise en charge de MathJax est optionnelle, c’est sans doute pour cela que ce choix a été fait : https://rust-lang.github.io/mdBook/format/mathjax.html
    Cela dit, il est probable que le JS de MathJax recharge d’autres fichiers depuis le CDN, donc il est difficile de comprendre pourquoi l’ensemble des fichiers MathJax n’est pas placé à côté du HTML généré
  • Il semble qu’une PR ouverte existe déjà à ce sujet : https://github.com/rust-lang/mdBook/pull/1918

• Les outils de documentation et de sites statiques mentionnés dans ce fil sont notamment Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook
  Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

  • J’ai aussi utilisé nimibook
    C’est un portage de mdBook en Nim, mais il a aussi été étendu pour générer du contenu interactif en utilisant le backend JavaScript de Nim. Je ne l’ai pas utilisé moi-même, mais j’aime l’idée de pouvoir créer des éléments interactifs au même endroit quand c’est nécessaire : https://pietroppeter.github.io/nimib/interactivity.html
  • Difficile de laisser de côté Sphinx. Son flux de travail est mieux adapté au format livre qu’aux formats blog, forum ou fil de discussion
  • HackMD est souvent un choix naturel pour créer des documents Markdown partageables et collaboratifs avec prise en charge des formules : https://hackmd.io/
  • Ce serait bien d’avoir un tableau ou un site comparatif des fonctionnalités de ces outils. J’aimerais comparer la recherche intégrée, la sortie PDF, la sortie ePub, plusieurs thèmes, et d’autres fonctions
  • Il y a aussi https://jupyterbook.org/en/stable/. Je contribue à Jupyter Book.

• J’ai essayé mdBook, Jekyll et MkDocs ; mdBook est élégant pour les projets de base, mais il m’a semblé trop minimaliste. En regardant le code source de sites mdBook qui me plaisaient, j’ai vu qu’ils étaient parfois étendus avec du code Rust personnalisé
  Ma recommandation : MkDocs comme choix par défaut raisonnablement flexible, Jekyll quand il faut plus de souplesse, par exemple pour une landing page ou un blog, et Antora si l’on veut construire le meilleur site de documentation en agrégeant plusieurs projets et plusieurs versions, et qu’on est prêt à y consacrer beaucoup d’efforts. AsciiDoc offre aussi de nombreuses fonctionnalités utiles pour rédiger de la documentation
  Hugo semble aussi flexible que Jekyll, mais demande davantage d’efforts pour être adapté comme on le souhaite, et les différences de fonctionnement entre les thèmes paraissent trop importantes. J’ai voulu changer de thème parce que celui que j’utilisais n’avait pas les fonctions nécessaires, mais la transition n’a pas été simple, donc j’ai fini par abandonner. mdBook semble assez actif, donc il finira probablement par rattraper son retard

  • J’utilise Jekyll depuis longtemps, et je pense qu’il reste excellent pour les blogs, mais parmi les générateurs de sites statiques pour la documentation, Docusaurus est celui que j’ai préféré : https://docusaurus.io/
    J’ai longtemps repoussé son usage parce que je ne voulais pas d’un outil basé sur JavaScript, mais après l’avoir essayé, j’ai trouvé qu’il était facile à démarrer, très rapide, avec un site par défaut beau et simple à personnaliser. Le support de MDX est aussi excellent
  • La landing page du thème material mkdocs(https://squidfunk.github.io/mkdocs-material/) est vraiment très soignée. C’est particulièrement impressionnant quand on pense qu’il s’agit d’un thème pour un logiciel tiers
  • Pour la science et les statistiques, Quarto me paraît excellent : https://quarto.org
  • Je découvre Antora, mais son approche consistant à assembler la documentation depuis plusieurs dépôts et à gérer les versions par branches correspond exactement à ce que je cherche. En revanche, le fait qu’il n’utilise pas MDX est regrettable, puisque ma documentation actuelle combine Markdown et composants React interactifs
  • J’utilise beaucoup MkDocs et je l’aime vraiment beaucoup
    J’essaie aussi BookStack, qui est plus proche d’un wiki, mais convient mieux aux personnes moins à l’aise avec la technique. En général, un projet MkDocs s’édite dans VSCode et vit dans un dépôt Git, tandis que BookStack est entièrement basé sur le web

• J’utilisais autrefois GitBook pour générer til.secretGeek.net, mais avec le temps c’est devenu de plus en plus lent : il fallait 45 minutes pour construire le site, et les fonctionnalités que j’utilisais ont été soit abandonnées, soit déplacées vers une offre “premium”. En gros, l’enshittification avait commencé
  Si vous utilisez un outil gratuit qui a l’air trop beau pour être vrai, il y a de fortes chances qu’il se dégrade au bout de quelques années. J’ai donc fini par recréer un générateur de site statique extrêmement minimal en .NET, et le site se reconstruit de nouveau en quelques secondes. Je ne le promeus pas particulièrement auprès des autres, parce que s’il devenait populaire, je finirais sans doute moi aussi par le dégrader de la même manière

  • “spruik” est un terme d’argot australien qui signifie faire de la promotion publiquement, en particulier de manière tapageuse, comme un bonimenteur ou un vendeur
    https://www.collinsdictionary.com/jp/dictionary/english/spru...

• J’ai utilisé mdBook sur plusieurs projets, mais ces derniers temps je trouve que material for mkdocs est plus agréable à utiliser, car il offre bien davantage de fonctionnalités prêtes à l’emploi
  Par exemple, j’aime beaucoup la table des matières de page à droite, une fonctionnalité qui manque de façon assez évidente dans mdBook. Avec mdBook, la norme semble être de construire un SUMMARY très détaillé et de découper en plusieurs fichiers un contenu qui pourrait autrement tenir sur une seule page

  • material for mkdocs vaut largement le coût d’une installation Python et de la configuration d’un environnement virtuel
  • Cela fait assez longtemps que j’apprécie MkDocs. Il permet de faire le travail avec un minimum de friction, propose beaucoup de thèmes au choix, et il est relativement facile à personnaliser ou à recréer soi-même
  • J’utilise https://github.com/JorelAli/mdBook-pagetoc pour obtenir une table des matières par chapitre

• Il y a quelques jours, j’ai commencé à utiliser mdBook pour documenter un petit projet, et c’est exactement le petit générateur de pages statiques qu’il me fallait
  J’ai aussi essayé HUGO, mais comparé à mdBook il me semble trop gros et trop lourd. Aujourd’hui, j’édite la documentation dans Obsidian/VIM et, dès que je pousse sur Gitea, la documentation publique est générée en moins d’une minute

  • J’utilise Hugo avec le thème book(https://github.com/alex-shpak/hugo-book). Si l’on n’est pas familier avec Hugo, il faut un temps d’adaptation, mais ensuite on apprécie la souplesse qu’apportent les shortcodes et autres fonctionnalités de Hugo
    Avec les bons shortcodes, on peut automatiser la numérotation des figures, des formules, etc. Je me demande si mdBook permet aussi une numérotation automatique. Il y a également une table des matières à droite, des tags, la possibilité de diviser les pages en colonnes, et un bon support de KaTeX. mdBook semble utiliser MathJax, et le déploiement est simple avec un push ou juste rsync
  • J’ai récemment commencé à utiliser une extension PlantUML, qui aide à insérer des diagrammes d’architecture dans la documentation

• J’ai récemment commencé à migrer lentement du contenu de .md vers .mdx, et l’expérience m’a paru assez rafraîchissante. Le point le plus pénible avec Markdown, c’était que chaque dialecte avait ses propres limites, et que la manière de les étendre variait tout autant.
  Je suis très satisfait de 80 à 90 % du dialecte Markdown standard de GitBook, mais il arrive qu’on ait besoin de tableaux complexes, de blocs de code où seules quelques lignes sont mises en évidence tout en conservant la coloration syntaxique, de sliders interactifs, d’une calculatrice intégrée dans le document, ou de certains graphiques et diagrammes. Je ne sais pas comment MDX fonctionnerait dans une grande équipe, mais pour un travail personnel, cela semble clairement être une amélioration.

  • Je découvrais .mdx et je suis allé voir [0]. Je n’avais pas suffisamment suivi la vague de standardisation du frontend.
    Ce serait bien que les dialectes disparaissent au profit d’une approche universelle, mais la documentation dit que « MDX n’est pas lié à React et peut aussi être utilisé avec Preact, Vue, Emotion, Theme UI, etc., tout en prenant en charge les runtimes JSX classic et automatic ». Il existe déjà une implémentation Svelte [1], donc je ne sais pas si cela n’ouvre pas simplement une nouvelle boîte de Pandore de dialectes liés aux frameworks frontend. Il pourrait déjà y avoir des divergences au sein même de .mdx, sans parler d’une incompatibilité avec .md.
    [0] https://mdxjs.com/docs/what-is-mdx/
    [1] https://mdsvex.com/docs
  • Tout à fait d’accord. Découvrir Mdsvex a été une révélation : https://mdsvex.com
  • .mdx s’utilise très facilement avec https://astro.build/. Astro est un métacadre JavaScript qui privilégie une approche orientée génération de site statique sans envoyer de JS au client.
    Il existe des thèmes prêts à l’emploi, mais pour un développeur web moderne, en créer un soi-même reste assez facile.

• J’ai créé KeenWrite, un outil gratuit, open source et multiplateforme pour produire des livres à partir de Markdown : https://github.com/DaveJarvis/keenwrite
  KeenWrite invoque ConTeXt pour la composition des documents et utilise un fork de KeenType pour le rendu des formules en mode aperçu. Il peut générer des PDF en ligne de commande. Le livre sur lequel je travaille actuellement référence dans le corps du texte plusieurs variables définies dans des fichiers externes, transmet des propriétés PDF via les métadonnées, et permet de ne construire que certains chapitres avec l’argument chapters. Le répertoire theme contient les instructions de composition pour les couleurs, les polices, la mise en page, les annotations, etc.
  Exemple de sortie : https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

• Je me demande pourquoi Markdown, ou quelque chose de proche, n’est pas le format par défaut pour les livres, la documentation, et presque tous les types d’écrits. Depuis que je suis passé à Typora il y a quelques années, je n’ai presque plus besoin de Word/Writer pour mes propres textes, seulement pour ouvrir des documents envoyés par d’autres.
  Même pour 90 % des livres que je lis, je ne vois pas de raison évidente pour qu’ils ne soient pas au format Markdown. Je comprends qu’une belle impression papier demande un vrai travail de composition, mais la plupart des textes lus sur ordinateur ou smartphone, ou imprimés directement depuis MS/LibreOffice, ne bénéficient de toute façon pas vraiment de ce niveau de mise en forme.

  • Markdown est assez pauvre comme format de stockage. Il existe un quasi-standard, CommonMark, mais il manque de fonctionnalités, donc la plupart des gens utilisent autre chose comme GitHub Markdown, et il arrive aussi que des applications étendent Markdown de façon mutuellement incompatible.
    Il existe de meilleures alternatives comme AsciiDoc, mais elles sont davantage spécialisées dans la documentation et n’ont pas la même dynamique que Markdown. Si l’on considère que Markdown est un format relativement tardif, la vraie question serait plutôt : pourquoi les livres devraient-ils être en Markdown ? Son principal avantage face aux formats binaires ou basés sur XML est qu’il reste lisible comme texte brut dans une certaine mesure, ce qui importe peu à la plupart des éditeurs et des lecteurs.
  • La composition de livres comporte beaucoup de subtilités et de complexité invisibles pour un œil non formé, et Markdown+CSS n’est pas assez sophistiqué pour tout cela. HTML/CSS+JS peut techniquement le faire, mais reste très loin de l’état de l’art en composition numérique.
    C’est aussi un piège classique d’ingénieur, celui de penser « je peux faire mieux », donc il ne faut pas partir de cette hypothèse sans se renseigner. La composition est un domaine bien plus ancien que les outils évoqués ici, avec un long héritage d’idées et de techniques précieuses qu’il ne faut pas balayer simplement parce que Markdown est presque suffisant pour certains usages.
  • J’écris beaucoup de documentation au travail, et j’aime bien voir Markdown et le rendu côte à côte. Une fois la syntaxe maîtrisée, Markdown est bien plus rapide qu’un éditeur comme Word, et même faire une simple liste dans un éditeur de texte finit par sembler fastidieux.

• mdBook est facile à utiliser, et j’apprécie particulièrement le fait que l’utilisateur puisse choisir son thème. Je l’utilise surtout pour la version en ligne de mes ebooks [0] et pour des ressources que j’ai sélectionnées [1][2].
  [0] https://github.com/learnbyexample/scripting_course#ebooks
  [1] https://learnbyexample.github.io/py_resources/
  [2] https://learnbyexample.github.io/curated_resources/