Installation

Il existe plusieurs façons d’installer l’outil en ligne de commande mdBook. Choisissez la méthode qui correspond le mieux à vos besoins. Si vous installez mdBook pour un déploiement automatique, consultez le chapitre sur l’intégration continue pour obtenir des exemples d’installation.

J’ai conservé l’ordre initial de la documentation officielle dans cette page.

Je recommande pour ma part :

• d’installer mdBook via la commande cargo install mdbook ou
• d’utiliser la version du paquet proposée par votre distribution Linux ou
• de récupérer l’exécutable compatible avec votre architecture.

Binaires pré-compilés

Des binaires exécutables sont disponibles en téléchargement sur la page des versions (Releases) de GitHub. Téléchargez le binaire correspondant à votre plateforme (Windows, macOS ou Linux) et extrayez l’archive. L’archive contient un exécutable mdbook que vous pouvez lancer pour générer vos livres.

Voir Installation de mdBook > installation isolée.

Pour faciliter son exécution, ajoutez le chemin d’accès au binaire dans votre variable d’environnement PATH ou copiez l’exécutable produit dans un dossier adéquat (dans Linux, ~/.local/bin ou /usr/local/bin).

Compiler à partir des sources en utilisant Rust

Pour compiler l’exécutable mdbook à partir des sources, vous devrez d’abord installer Rust et Cargo. Suivez les instructions de la page d’installation de Rust. mdBook requiert une version 1.88 ou supérieure de Rust.

Une fois Rust installé, utilisez la commande suivante pour compiler et installer mdBook :

cargo install mdbook

Cela va automatiquement télécharger mdBook depuis crates.io, le compiler et l’installer dans le répertoire global des binaires de Cargo (~/.cargo/bin/ par défaut). Vous pouvez vous assurer que le dossier est dans votre PATH ou copier l’exécutable produit dans un dossier adéquat (dans Linux, ~/.local/bin ou /usr/local/bin).

Vous pouvez exécuter à nouveau cargo install mdbook chaque fois que vous souhaitez effectuer une mise à jour vers une nouvelle version. Cette commande vérifiera si une version plus récente existe et réinstallera mdBook si c’est le cas.

Pour le désinstaller, exécutez la commande

cargo uninstall mdbook

Installer la dernière version master

La version publiée sur crates.io est très légèrement en retard par rapport à celle hébergée sur GitHub. Si vous avez besoin de la toute dernière version, vous pouvez compiler vous-même la version git de mdBook. Cargo rend cela extrêmement facile !

cargo install --git https://github.com/rust-lang/mdBook.git mdbook

Assurez-vous d’ajouter le répertoire bin de Cargo à votre PATH ou de copier l’exécutable produit dans un dossier adéquat (dans Linux, ~/.local/bin ou /usr/local/bin).

Modification et contribution

Si vous souhaitez apporter des modifications à mdBook lui-même, consultez le Guide de contribution (Contributing Guide) pour plus d’informations.

Distributions Linux

Les concepteurs·trices de mdbook ne parlent pas des intégrations de l’outil dans les distributions Linux.

mdbook est pourtant bel est bien proposé dans les distributions Linux.

Exemples :

• Linux Debian : https://packages.debian.org/stable/utils/mdbook ;
• Arch Linux : https://archlinux.org/packages/extra/x86_64/mdbook/ ;
• Fedora : https://packages.fedoraproject.org/pkgs/rust-mdbook/mdbook/ ;
• Ubuntu : https://packages.ubuntu.com/ca/stonking/ppc64el/utils/mdbook ;
• etc.