Paramétrage de mdBook : book.toml

À ce stade de votre découverte, il est probable que nous ne compreniez pas tous les champs contenus dans mon fichier d’exemple. Tout ceci viendra naturellement et progressivement pendant votre apprentissage.

Le fichier de paramètres pour notre projet mdBook se trouve à la racine de notre projet (nom-du-projet/) et se nomme book.toml.

Recommandation importante

Plutôt que de perdre notre temps à structurer des tables et sous-tables (ou sections et sous-sections) TOML, je recommande vivement de travailler « à plat ».

Ainsi, plutôt que :

[book]
title = "Apprendre et maîtriser mdBook"
authors = ["Marc JESTIN"]
language = "fr"

[output.html]
additional-css = ["custom.css"]
additional-js = ["custom-ace.js"]
sidebar-header-nav = false
mathjax-support = true

[output.html.playground]
line-numbers = true
editable = true

[rust]
edition = "2024"

nous privilégions :

book.title = "Apprendre et maîtriser mdBook"
book.authors = ["Marc JESTIN"]
book.language = "fr"
output.html.additional-css = ["custom.css"]
output.html.additional-js = ["custom-ace.js"]
output.html.sidebar-header-nav = false
output.html.mathjax-support = true
output.html.playground.line-numbers = true
output.html.playground. editable = true
rust.edition = "2024"

En réalité, les contenus des [] sont une partie (le début) de chaînes d’identification complètes.
Tout serait simple s’il n’y avait des règles à respecter qui nous obligent parfois à refactorer notre fichier plus lourdement pour ajouter un seul paramètre si nous avons écrit notre fichier avec des sections.
CONCLUSION : tout à plat et on gagne du temps !

Documentation, présentation

Si nous souhaitons que ce soit plus facile à relire, nous pouvons :

• aérer en ajoutant des lignes vides ;
• modifier l’ordre à souhait ;
• ajouter des commentaires avec le caractère croisillon # n’importe où dans une ligne.

Par exemple :

# Configuration générale du livre
book.title = "Apprendre et maîtriser mdBook"
book.authors = ["Marc JESTIN"]
book.language = "fr"

# Styles et scripts personnalisés
output.html.additional-css = ["custom.css"]
output.html.additional-js = ["custom-ace.js"] # Patch de contournement pour Ace Editor

# Interface utilisateur
output.html.sidebar-header-nav = false

# Support des formules mathématiques
output.html.mathjax-support = true

# Configuration des blocs de code Rust interactifs
output.html.playground.line-numbers = true
output.html.playground.editable = true

# Version du compilateur Rust pour le Playground
rust.edition = "2024"