MdBook

MdBook est un GitBook like écrit en Rust, mais, contrairement à GitBook, il a gardé sa simplicité.

Le principe est simple, vous écrivez vos articles / chapitres en MarkDown, vous organisez votre sommaire, et vous générer le book en format html.

La documentation officielle est faite avec mdbook ainsi que ce « blog » que vous êtes en train de lire.

Installation

J'ai opté pour la méthode la plus simple : récupérer le binaire linux sur leur dépôt git : https://github.com/rust-lang/mdBook/releases et extraire le binaire dans un dossier qui est dans mon PATH.

Et voila, mdbook est installé.

CLI

C'est donc un outil en CLI très simple à utiliser.

Comme tout bon outil CLI, une aide très claire est présente :

mdbook -h

mdbook v0.4.7
Mathieu David <mathieudavid@mathieudavid.org>
Creates a book from markdown files

USAGE:
    mdbook [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    build    Builds a book from its markdown files
    clean    Deletes a built book
    help     Prints this message or the help of the given subcommand(s)
    init     Creates the boilerplate structure and files for a new book
    serve    Serves a book at http://localhost:3000, and rebuilds it on changes
    test     Tests that a book's Rust code samples compile
    watch    Watches a book's files and rebuilds it on changes

For more information about a specific command, try `mdbook <command> --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook

Initialisation

Pour commencer, on execute la commande suivante :

mdbook init

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book? 
Example book
2021-04-24 16:41:57 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

On se retrouve avec la structure de fichier suivante :

.
├── book
├── book.toml
└── src
    ├── chapter_1.md
    └── SUMMARY.md

Construction du book

Pour générer le book en html, on éxécute simplement la commande suivante :

mdbook build

2021-04-24 17:07:57 [INFO] (mdbook::book): Book building has started
2021-04-24 17:07:57 [INFO] (mdbook::book): Running the html backend

Le book est généré dans le dossier <projet>/book/ :

./book
├── 404.html
├── ayu-highlight.css
├── book.js
├── chapter_1.html
├── clipboard.min.js
├── css
│   └── [...]
├── elasticlunr.min.js
├── favicon.png
├── favicon.svg
├── FontAwesome
│   └── [...]
├── fonts
│   └── [...]
├── highlight.css
├── highlight.js
├── index.html
├── mark.min.js
├── print.html
├── searcher.js
├── searchindex.js
├── searchindex.json
└── tomorrow-night.css

Il vous suffit d'ouvrir le fichier index.html pour voir le book.

Construction à la volée

Lors de la rédaction de vos articles, vous ne voudrez pas faire manuellement un mdbook build à chaque changement.

Pour ce faire, la commande mdbook watch permet de reconstruire le book à chaque sauvegarde d'article.

Cela permet d'avoir le rendu (moyennant un rafraîchissement manuel) dans son navigateur pendant qu'on rédige un article dans son IDE préféré.