Modification des feuilles de style mdBook

Les manipulations décrites ici et dans les sous-chapitres sont parfaitement licites et prévues par mdBook.
La documentation nous indique que :

« Le thème est totalement personnalisable, vous pouvez remplacer sélectivement chaque fichier du thème par le vôtre en ajoutant un dossier theme/ à côté du dossier src/ à la racine de votre projet. » ¹

Le compilateur mdBook fonctionne sur le principe de la surcharge :

• Si nous avons défini un fichier, par exemple theme/css/general.css, alors le compilateur s’appuie sur ce fichier pour construire le site web mdBook cible.
• Sinon, le compilateur mdBook utilise son fichier de base.

Nous disposons d’une autre surcharge que nous traitons dans Définition de styles CSS personnalisés dans mdBook.

Récupération des feuilles de styles d’origine

Les feuilles de styles font partie des thèmes mdBook.

Pour récupérer une copie des fichiers d’origine, nous pouvons, en nous plaçant dans le dossier racine de notre projet mdBook, utiliser la commande :

mdbook init --theme temp # temp ou un autre nom de dossier qui n'existe pas

La commande crée cette arborescence de fichiers :

temp
├── book
├── book.toml
├── src
│   ├── chapter_1.md
│   └── SUMMARY.md
└── theme
    ├── book.js
    ├── css
    │   ├── chrome.css
    │   ├── general.css
    │   ├── print.css
    │   └── variables.css
    ├── favicon.png
    ├── favicon.svg
    ├── fonts
    │   ├── fonts.css
    │   ├── OPEN-SANS-LICENSE.txt
    │   ├── open-sans-v17-all-charsets-300italic.woff2
    │   ├── open-sans-v17-all-charsets-300.woff2
    │   ├── open-sans-v17-all-charsets-600italic.woff2
    │   ├── open-sans-v17-all-charsets-600.woff2
    │   ├── open-sans-v17-all-charsets-700italic.woff2
    │   ├── open-sans-v17-all-charsets-700.woff2
    │   ├── open-sans-v17-all-charsets-800italic.woff2
    │   ├── open-sans-v17-all-charsets-800.woff2
    │   ├── open-sans-v17-all-charsets-italic.woff2
    │   ├── open-sans-v17-all-charsets-regular.woff2
    │   ├── SOURCE-CODE-PRO-LICENSE.txt
    │   └── source-code-pro-v11-all-charsets-500.woff2
    ├── highlight.css
    ├── highlight.js
    └── index.hbs

Les thèmes comportent :

• des feuilles de styles ;
• une favicon ;
• des polices de caractères au format woff2 ;
• un fichier index.hbs.

Nous ne traitons que des feuilles de styles dans cette section, mais nous copions l’intégralité du dossier theme/ à la racine de notre projet tout de même. Cela pourra toujours servir… 😉

Nous pouvons maintenant supprimer le dossier temp/ qui ne nous sert plus à rien.

Défrichage

Il nous faut maintenant défricher pour savoir qui fait quoi dans cette architecture de fichiers.

• ``theme/css/` « est le dossier contenant les fichiers CSS pour le style » ² :
  • css/chrome.css : gère les éléments de l’interface utilisateur.
  • css/general.css : définit les styles de base.
  • css/print.css : définit les styles pour l’impression.
  • css/variables.css : contient les variables utilisées dans les autres fichiers CSS.

Ce fichier n’est pas dans le dossier CSS (?!). Il est dans theme/ tout court, à côté du fichier JavaScript qui va avec. Il s’agit de la feuille de styles pour la coloration syntaxique des blocs de code :

• highlight.css

Ce fichier non plus n’est pas dans le dossier CSS ! (Décidément !) Il s’agit du fichier de déclaration des polices utilisées, et il est avec les polices en question dans le dossier theme/fonts :

• fonts/fonts.css. ³

Au boulot !

Clairement, pas mal de choses ne vont pas du tout dans les feuilles de styles proposées par mdBook par défaut.

Par exemple, si nous utilisons des zones extensibles (<details>) dans nos pages mdBook, celles-ci ne sont pas développées lorsque nous créons la version imprimable du livre. Dommage, Éliane !

1. https://github.com/rust-lang/mdBook/blob/master/guide/src/format/theme/README.md ↩

2. Je cite la documentation qui, sur quelques lignes, nous livre une superbe démonstration de dissonance cognitive. ↩

3. Quand on commence à défricher un code source et que l’on s’aperçoit de telles dissonances cognitives, on peut commencer à s’inquiéter quant à la qualification et la santé mentale des développeurs·ses qui l’ont produit… De mon point de vue. ↩