Créer un site Web local de documentation pouvant exporter en PDF avec mdBook

La documentation du langage Rust (le langage qui veut remplacer le C et le C++ en sécurisant l’accès mémoire et en supprimant le ramasse-miette) est écrite en Markdown.

Comme cette documentation doit pouvoir suivre l’évolution du langage (et donc évoluer avec chaque version de Rust) l’équipe Rust a créé mdBook pour pouvoir générer un livre en PDF à partir de chapitres HTML écrits en Markdown.

Licence de mdBook

mdBook est un logiciel libre sous licence Mozilla Public Licence v2.0.

Vous pouvez en trouver les sources pour y contribuer sur GitHub (https://github.com/rust-lang/mdBook).

Pour savoir comment contribuer à améliorer mdBook suivez le guide en anglais (https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md).

Installation de mdBook 0.52

Les fichiers sources d’installation sont disponibles sur GitHub pour MacOS, Windows, et Linux.

Vous pouvez aussi installer mdBook, si vous avez installé au préalable le langage Rust sur votre ordinateur en écrivant dans une fenêtre de Terminal la commande :
cargo install mdbook

Comme cela vous pourrez voir en direct comment cargo compile un programme Rust.

Création de votre mdBook

Mettez mdBook dans la variable PATH de votre poste, pour lancer les commandes mdbook depuis n’importe quel endroit.

Pour créer un mdBook, utilisez votre terminal pour lancer la commande mdbook init livre-exemple.
Cette commande créera le répertoire vide « livre-exemple ».
mdBook vous posera alors plusieurs questions pour créer votre premier livre vide.

Allez dans ce nouveau répertoire avec la commande cd livre-exemple (\home\nom_utilisateur\livre-exemple sur un ordinateur GNU/Linux).

Puis lancez le serveur Web local de votre livre avec la commande mdbook serve --open.

Cette commande va lancer le serveur Web local et ouvrir votre navigateur par défaut sur votre mdBook vide.

Fichiers de configuration

book.toml

Ce fichier contient le titre de votre futur livre dans le champ "title".
Il contient aussi un champ « author » à renseigner avec votre nom (ou votre pseudo-littéraire) et un champ « langage » qui par défaut à la valeur « en », mais que vous pouvez évidemment modifier en « fr » avec votre éditeur de texte favori (gedit par exemple sous GNU/Linux).

src/SUMMARY.md

Ce fichier contient la structure de votre futur livre (la liste des chapitres).
Pour créer facilement un chapitre, une préface, une introduction, une annexe… ajoutez des lignes dans ce fichier Markdown.

Par exemple :

    # Summary

    - [00-Introduction](./Introduction.md)
    - [01-Mon premier chapitre](./01-mon-premier-chapitre.md)

Les chapitres seront créés vides dans le répertoire src au fur et à mesure de votre saisie dans le fichier src/SUMMAY.md par le programme mdBook.

Publication de votre mdBook

Une fois vos chapitres créés en Markdown avec votre éditeur de texte, publiez votre mdBook avec la commande :
mdbook build.
Cette commande créera un répertoire \livre-exemple\book. Vous pourrez diffuser ce sous-répertoire « book » sur votre serveur Web en le transférant par FTP.

Astuce : rien ne vous empêche de renommer ce répertoire « book » en fr-livre-exemple-2026 avant de le transférer en FTP sur votre serveur Web.

Les 4 fonctionnalités de votre mdBook

1) La table des matières s’affiche en cliquant sur le menu hamburger en haut à gauche de votre page Web.

2) Vous pouvez changer le thème de votre page Web en cliquant sur le pinceau (par défaut le thème affiché est « Auto »).

3) Vous pouvez chercher un mot dans votre mdBook en cliquant sur la loupe.

4) Vous pouvez imprimer ce livre (au format PDF, ou sur votre imprimante) en cliquant sur l’icône de l’imprimante en haut à droite de votre page Web.

Utilisations possibles de mdBook

Vous pouvez utiliser mdBook pour créer la documentation multilingue de votre logiciel libre (par exemple un mdBook en français et un mdBook en anglais), voire de votre distribution GNU/Linux préférée.

Vous pouvez préciser la licence de votre livre en créant un chapitre licence, et par exemple choisir de publier votre livre en licence Creative Commons, Cecill ou Art Libre.

Aller plus loin

• Langage Rust (9 clics)
• La traduction non-officielle de la documentation de Rust (6 clics)
• La documentation de mdBook (en mdBook) (30 clics)
• L'article de Korben sur le mdBook (25 clics)