mdBook : Questions avec réponses

Problèmes d’affichage des titres de chapitres de pages mdBook

Il peut arriver que nos titres de chapitres de pages mdBook ne soient pas interprétés correctement alors que « tout semble normal » dans votre code Markdown.

En effet, nous voyons bien dans notre code :

### Titre

et pourtant, le projet compilé affiche ceci :

### Titre

La raison est certainement que nous avons relâché la touche « AltGr » trop tard lorsque nous avons appuyé sur la touche « Espace » qui suit le dernier #.

Le caractère inséré n’étant pas pas stricto sensu une « Espace » (mais une espace insécable, dans Linux tout du moins), et le parseur Markdown n’ayant pas prévu ce cas, il ne crée pas un titre comme nous l’attendons.

Pour corriger cette erreur, il suffit de supprimer le AltGr + Espace (souvent invisible, sauf si nous avons fait ce qu’il faut dans notre éditeur) et de le remplacer par une Espace qui va bien.

Générer des liens bruts avec du code markdown mdBook ?

Il n’est pas possible d’afficher le lien brut par une autre méthode que celle de l’écrire en dur encadré par des « < > ».

Cette syntaxe n’est pas prévue :

[](Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.md#sous-chapitres)

Elle rend ceci :

Pas plus que :

(Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.md#sous-chapitres)

qui s’affiche comme ceci :

(Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.md#sous-chapitres)

Il est toujours possible d’écrire ceci :

[https://happynumeric.fr/Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.html#sous-chapitres](https://happynumeric.fr/Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.html#sous-chapitres)

(en lieu et place de :

<https://happynumeric.fr/Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.html#sous-chapitres>

)

Cela n’a aucun intérêt : Cela affiche effectivement exactement la même chose, mais avec plus d’efforts :

https://happynumeric.fr/Bloc-notes-mdBook/mdbook-markdown-chapitres-et-listes.html#sous-chapitres

Quel lien relatif dois-je mettre dans un `fichier.md` pour une insertion ?

Tout ce qui est écrit ici est correct (sauf coquille que j’aurais laissée passer).

Je recommande d’utiliser uniquement l’approche proposée dans « Bonne réponse », beaucoup plus simple et reproductible.

Avec cette bonne approche, nous pouvons copier-coller des structures de liens []() d’un fichier à l’autre sans nous poser de question.

Mauvaise réponse

Lorsque nous écrivons un fichier.md qui va être inséré dans un autre fichier.md, nous devons avoir le contexte que verra le compilateur mdBook à l’esprit.

Exemples.

Nous avons cette structure de fichiers :

nom-du-projet/
├── src/
    ├── SUMMARY.md
    ├── page-mdBook.md
    ├── page-mdBook-cible.md
    ├── fichiers-inseres/
        ├── fichier-insere.md

Dans page-mdBook.md, nous avons écrit la commande d’insertion suivante :

{{#include ./fichiers-inseres/fichier-insere.md}}

Nous souhaitons écrire un lien qui pointe vers page-mdBook-cible.md dans fichier-insere.md.

Nous devons considérer que nous écrivons ce lien dans un code qui sera interprété par le compilateur mdBook après que le pré-processeur aura réalisé l’insertion.
De ce fait, le compilateur interprétera ce lien comme s’il était écrit dans page-mdBook.md.

Ainsi, le lien à écrire dans fichier-insere.md est :

[Texte du lien](./page-mdBook-cible.md)

Si la structure de fichiers est la suivante :

├── src/
    ├── SUMMARY.md
    ├── page-mdBook.md
    ├── rubrique-1/
    │   ├── page-mdBook-cible.md
    ├── fichiers-inseres/
        ├── fichier-insere.md

Le lien à écrire dans fichier-insere.md est alors :

[Texte du lien](./rubrique-1/page-mdBook-cible.md)

Bonne réponse

La meilleure manière de faire sans se tromper consiste à écrire tous nos liens internes… en partant de la racine du projet mdBook et futur site web mdBook.

Pour ce faire, nous écrivons tous les liens sous la forme :

/dossier/sous-dossier/fichier

Le / du début symbolise la racine du site (comme lorsque nous travaillons en HTML).

La racine du projet mdBook est le dossier src/ et
la racine du site web mdBook est le dossier book/
- qui correspond à la racine du site web.

Si nous reprenons les exemples ci-avant, voici ce que cela donne.

Nous avons cette structure de fichiers :

nom-du-projet/
├── src/
    ├── SUMMARY.md
    ├── page-mdBook.md
    ├── page-mdBook-cible.md
    ├── fichiers-inseres/
        ├── fichier-insere.md

Dans page-mdBook.md, nous avons écrit la commande d’insertion suivante :

{{#include /fichiers-inseres/fichier-insere.md}}

Nous souhaitons écrire un lien qui pointe vers page-mdBook-cible.md dans fichier-insere.md.

Le lien à écrire dans fichier-insere.md est tout simplement :

[Texte du lien](/page-mdBook-cible.md)

Avec cette structure de fichiers :

nom-du-projet/
├── src/
    ├── SUMMARY.md
    ├── page-mdBook.md
    ├── rubrique-1/
    │   ├── page-mdBook-cible.md
    ├── fichiers-inseres/
        ├── fichier-insere.md