mdBook : Atouts et limites

Cette page a été écrite en mars 2023.

mdBook présente des avantages et des inconvénients, des atouts et des limites.

Je vous propose de vous donner mon analyse ici.

Une utilisation fastidieuse

Un éditeur est plus pratique

Le problème de l’approche en mode compilation d’un document, ou d’un site Web est que cela est plus fastidieux et pénible à la longue qu’une simple édition surtout s’il s’agit d’une édition WYSIWYG, en voyant directement le résultat de notre travail comme dans Wordpress ou MédiaWiki par exemple.

Il manque des outils à valeur ajoutée comme la correction orthographique et grammaticale

Par ailleurs, l’absence d’un éditeur riche nous prive de la correction orthographique et grammaticale que nous avons avec des outils de type CMS : comme nous les utilisons dans le navigateur web, nous pouvons nous servir d’extensions pour nous aider à repérer nos fautes dans le texte.

L’absence de continuité et de « mode plan » (dynamique) est très pénalisante

Par exemple, si nous modifions le titre d’un chapitre dans SUMMARY.md, il faut penser à :

• renommer le fichier md correspondant à la fois dans le lien entre parenthèses et dans la structure de dossiers et fichiers ET
• modifier le titre qui s’affiche en haut du fichier .md correspondant.

Il peut exister des versions décalées

Du fait du fonctionnement du système, nous sommes comme dans le cadre d’un programme en développement.

De ce fait, l’auteur ou les auteurs d’un projet mdBook peuvent être en train de travailler sur la prochaine version alors qu’elle n’est pas encore chargée sur le site de production.

C’est assez habituel dans le monde du développement.

Ça l’est moins pour des béotiens qui peuvent être perturbés par cela.

Des fonctionnalités très limitées

mdBook n’offre pas grand chose comme possibilités.

On ne peut pas, par exemple :

• intégrer des vidéos comme on intègre des images ;
• etc.

Quels avantages ?

Mais alors, quels sont les avantages de ce produit ?

Utiliser mdBook, c’est intégrer la logique de la communauté Rust et espérer que l’outil sera enrichi à l’avenir.

Utiliser mdBook, c’est bénéficier de cette logique de site compilé (« buildé ») et a priori donc plus performant et plus sûr.
Propos à nuancer car

• un site Web mdBook comporte des scripts que la plupart des utilisateurs ne vérifieront pas ;
• mdBook s’appuie sur une chaîne d’approvisionnement, qu’il ne respecte pas complètement puisque nous savons que les modifications dans handlebars.

Utiliser mdBook, c’est bénéficier de l’outil de compilation et d’exécution de codes Rust intégré.
Voilà là un avantage bien mince lorsque l’on sait à quel point :

• le Playground Rust est accessible et propose de plus en plus d’outils ;
• il n’est pas difficile de reprendre le code d’intégration pour s’en servir ailleurs.

« Pourquoi c’est faire ? »

Une des questions que je pose toujours est : « Pourquoi les développeurs ont-ils décidé de le produire alors même qu’il existait, au moment où ils ont fait ce choix, de nombreux outils capables de produire de la documentation de qualité ? »

Je n’ai franchement pas la réponse à cette interrogation à ce jour.

En synthèse

mdBook est un outil très limité qui ne peut convenir à ce jour et dans l’état de mes connaissances que pour construire un site en anglais (faute d’une logique de localisation sérieuse et facile d’accès) sous forme de livre et avec une présentation de sommaire « à plat » qui peut vite devenir interminable.

mdBook ne m’offre pas de perspectives importantes pour construire quelque-chose.

À tel point que je suis en train de réfléchir pour plutôt construire mes blocs-notes Rust avec un support type MediaWiki qui, de mon point de vue, est beaucoup plus pratique car il propose :

• une création dynamique et souple de site Web qui permet de générer nativement et sans effort la génération progressive du contenu ;
• des capacités à intégrer toutes sortes de médias audio, vidéo, images.
• une capacité d’extensibilité et de gestion de gros volumes de pages, qui n’a de limite que :
  • la créativité du gestionnaire ;
  • ses capacités de travail ;
  • sa capacité à créer une ou plusieurs approches de présentation et de parcours guidé de son contenu.
• le tout en offrant une immense souplesse quant aux manières d’exploiter l’outil.

Je pense que les développeurs de mdBook ont manqué de vista lorsqu’ils ont créé l’outil et qu’ils auraient pu, et dû, s’appuyer sur quelque-chose de « plus grand » et ne pas perdre de temps à créer cet outil.

Par ailleurs, la documentation est

• par trop orientée développeurs et
• incomplète et insuffisante.

Je vais toutefois continuer de consolider mes savoir-faire sur l’outil et de suivre ses évolutions à l’avenir.

En espérant que les besoins internes de la communauté les conduiront à développer un outil plus puissant, plus performant, plus riche, plus modulaire, et plus facile à paramétrer, localiser et gérer.

Tout un programme !

En juillet 2026, force est de constater que l’outil n’a que très peu évolué.