mdBook : Insérer un contenu

mdBook dispose d’un préprocesseur qui prépare une structure de fichiers à partir de ses différentes briques avant de passer aux autres étapes de la compilation.

L’insertion est le fait d’insérer le contenu d’un autre fichier dans le fichier en cours au point d’insertion que nous avons indiqué.

Le terme anglais est include qui signifie insérer.

Il est possible d’insérer des contenus à partir de fichiers dans mdBook pour :

• insérer le contenu d’un fichier.md dans un autre fichier.md ;
• insérer tout ou partie du contenu d’un fichier de code :
  • celui d’un fichier source en langage Rust
  • ou de tout autre langage informatique.

Par exemple voici ce que donne l’insertion d’un fichier de code javascript :

 document.getElementById("bonjour").innerHTML = "Bonjour !"; 

Insérer un contenu de fichier.md

Cette fonction est particulièrement utile si nous avons besoin :

• d’inclure le même contenu dans plusieurs pages mdBook ;
• de travailler sur plusieurs fichiers séparément dans le cadre d’un projet en équipe.

La syntaxe est {{#include lien-vers-le-fichier}}. Nous l’utilisons directement dans le contenu Markdown pour insérer le contenu d’un fichier .md.

Je recommande d’organiser cela par sous-dossiers pour que ce soit plus lisible.

Pour inclure un fichier, nous procédons comme suit :

• Nous créons un dossier bibliotheque par exemple dans le dossier source du projet mdBook nom-du-projet/src (par défaut).
• Dans ce dossier bibliotheque, nous créons un fichier bas-de-page.md contenant des éléments que nous souhaitons ajouter en bas de toutes les pages du site Web mdBook.
• Dans les fichiers.md, à l’endroit souhaité, nous ajoutons :

{{#include ./bibliotheque/bas-de-page.md}}

C’est fait !

Au moment de la compilation, mdBook se charge de réaliser l’insertion.

Lorsque nous réalisons une insertion, celle-ci est séparée du reste du contenu : ce ne peut être un texte inséré dans un paragraphe, ou partie de tableau dans un tableau, etc.

Insérer le contenu d’un fichier de code

L’insertion d’un code informatique se fait avec la même consigne, cette fois à l’intérieur d’un bloc de code.

La syntaxe est la suivante :

```rust
{{#include ./codes-rust/code-rust.rs}}
```

ou encore :

```javascript
{{#include ./codes-javascript/code-js.js}}
```

Options particulières

Il existe de nombreuses options spécifiques dans le cas d’insertion dans des blocs de codes.
Nous les abordons dans d’autres pages mdBook.

Cas particulier de SUMMARY.md

Il n’est pas possible de réaliser d’insertion dans SUMMARY.md.