Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

mdBook : Architecture des fichiers

Un projet mdBook se crée et vit sa vie dans un dossier local.

Lorsque nous validons la commande suivante en étant dans le dossier nom-du-projet/

mdbook init

et que nous répondons y à la première question (création d’un fichier .gitignore), mdBook crée une base de fichiers dans notre dossier nom-du-projet/.

Le fichier de paramétrage de notre projet mdBook est book.toml.

Les fichiers de création de contenu sont dans le dossier nom-du-projet/src (par défaut).
C’est dans ce fichier book.toml que nous pouvons indiquer un autre emplacement si nous le souhaitons.

Lorsque, en étant dans le dossier nom-du-projet/, nous construisons les fichiers destination avec la commande :

mdbook build

mdBook crée l’ensemble des fichiers et dossiers nécessaires au fonctionnement du site Web statique mdBook dans le dossier nom-du-projet/book (par défaut).

Site web statique

mdBook est un générateur de site web statique (SSG = Static Site Generator).

Un site web statique, à l’inverse des sites web dynamiques comparables connus sous l’acronyme CMS (Content Management Systems) :

  • est servi par un serveur HTTP très simple (comme Nginx, Apache, Caddy, etc) ;
  • ne présente aucun risque en matière de sécurité du serveur (le contenu n’est pas un code informatique) ;
  • est généralement bien plus rapide à afficher (le serveur se contente de transmettre des fichiers) ;
  • peut contenir des parties « dynamiques » dans son fonctionnement, qui sont gérées par des scripts JavaScript téléchargés depuis le serveur web vers le navigateur web, puis exécutés grâce à l’interpréteur du navigateur web.

Chargement du site sur un serveur externe

Un projet mdBook peut tout à fait être un projet de documentation local : il suffit alors de disposer de mdbook et d’utiliser mdbook serve, ou même simplement de parcourir les fichiers du site web compilé.

Si nous disposons d’un serveur web et souhaitons publier le projet mdBook, il suffit de copier le contenu du dossier nom-du-projet/book dans un dossier correspondant à l’adresse que nous souhaitons donner à notre site web mdBook (ou un dossier mappé si nous utilisons Docker par exemple).

Voilà pour le fonctionnement de base de mdBook.

Cela suffit pour créer un projet mdBook sur notre machine, le partager avec des tiers et, si nous le souhaitons, le mettre en ligne pour qu’il soit accessible sur le World Wide Web (comme ce site).