mdbook serve : visualiser nos modifications en continu

mdBook propose un outil qui fournit un service pour visualiser nos modifications en continu sur notre machine de travail : mdbook serve.

mdbook serve :

• surveille nos modifications des fichiers.md (lorsque nous les enregistrons) ;
• compile le livre (book) en continu (lorsqu’il détecte des modifications) ;
• fournit un serveur Web intégré (d’où son nom) ;
• affiche automatiquement la nouvelle version des pages web mdBook ouvertes dans notre navigateur web si des modifications ont été enregistrées sans que nous ayons besoin de faire quoique ce soit.

Commande de base

La commande de base, à saisir dans le dossier nom-du-projet/ est :

mdbook serve

Par défaut, nous accédons au serveur Web intégré correspondant en nous rendant à l’adresse :

http://localhost:3000 # http, pas https (puisque local)

Commande avec ouverture du navigateur web

L’option --open ou simplement -o ouvre la visualisation du livre dans notre navigateur web par défaut :

mdbook serve -o

Indiquer un autre port

En cas de besoin, nous pouvons travailler sur un autre port grâce à l’option -p numdeport, par exemple :

mdbook serve -o -p 5555

Est-il obligatoire d’utiliser mdbook serve ?

Nous pouvons ne pas utiliser mdbook serve.

Nous utilisons alors la commande :

mdbook build

pour compiler notre projet mdBook.

Nous pouvons alors visualiser un aperçu du site Web mdBook en ouvrant les fichiers du dossier nom-du-projet/book (par défaut) dans notre navigateur web.

Certains composants ne fonctionnent pas comme dans la version web de notre projet mdBook.

C’est bien plus pratique avec mdbook serve qui nous fait gagner beaucoup de temps, surtout si nous savons écrire et utiliser des scripts.

Assistance apportée par mdbook serve

Lorsque nous faisons tourner mdbook serve, celui-ci effectue certaines tâches automatiquement pour nous.

mdbook serve se charge notamment de créer, lorsqu’ils n’existent pas, les fichiers.md que nous avons définis dans le SUMMARY.md. Si nécessaire, mdbook serve crée la structure de dossiers que nous y avons définie.

Par exemple, si nous ajoutons ceci dans SUMMARY.md (et que les dossiers et fichiers n’existent pas déjà) :

#![allow(unused)]
fn main() {
- [Comment faire](./comment-faire/introduction.md)
  - [Première étape](./comment-faire/premiere-etape.md)
    - [Préambule](./comment-faire/premiere-etape/preambule.md)
}

mdbook serve se charge automatiquement, dès l’enregistrement du fichier sommaire,

• de créer les dossiers, sous-dossiers et fichiers et
• d’insérer les titres de niveau 1 dans les fichiers soit
  • # Comment faire dans le fichier introduction.md,
  • # Première étape dans premiere-etape.md et
  • # Préambule dans preambule.md.