mdBook : sommaire : spécificités

Le fichier du sommaire mdBook, SUMMARY.md a une fonction particulière dans mdBook.

Syntaxe

Cas particulier

La première ligne débutant par un # du fichier ET écrite AVANT le premier chapitre de sommaire n’est pas affichée dans le sommaire mdBook du site Web mdBook.

C’est la raison pour laquelle le # Summary du début du fichier n’est ni interprété ni affiché.

Nous pouvons le supprimer sans que cela n’ait de conséquence pratique sauf si nous avions écrit une rubrique du sommaire juste après : celle-ci n’est plus affichée dans notre sommaire mdBook.

Je recommande de laisser la toute première ligne du fichier qui a été écrite lors de la création du projet mdBook en place et de ne pas la modifier.

# Summary (laisser en première position du fichier SVP).

Rappel des règles d’écriture du sommaire mdBook

Le # signifie que nous écrivons une rubrique du sommaire.
Il n’existe pas de sous-niveaux.

Les chapitres de sommaire et sous-chapitres de sommaire s’écrivent avec - []() (numérotés) ou avec []() (non numérotés).
Ils s’indentent pour indiquer des sous-niveaux.

Voir mdBook : SUMMARY.md : Structurer les pages mdBook.

Jonction sommaire => pages

Un chapitre de sommaire défini par son titre dans SUMMARY.md correspond à une page mdBook.

Cette page mdBook est décrite dans un fichier.md.

Ce contenu dans SUMMARY.md :

[Présentation](./presentation.md)

indique que le fichier presentation.md contient la description (en code Markdown) du chapitre « Présentation » du projet mdBook.

Ce qui suit rentre dans la logique de construction d’un projet mdBook décrite dans mdBook : SUMMARY.md : Structurer les pages.

S’il a été créé par le compilateur mdBook (dont se sert mdbook serve en continu si nous l’avons démarré), le fichier presentation.md comporte son titre (indiqué entre [] dans le sommaire mdBook) sous le format :

# Présentation

Un lien certes, mais pas le même

La syntaxe

[Texte du lien interne](lien-interne)

a apparemment le même comportement : créer un lien vers une autre page (oui, mais pas nécessairement une page mdBook).

En réalité, le compilateur traite d’autres opérations lorsqu’il s’agit d’un lien présent dans SUMMARY.md.

Par ailleurs, si le [ est précédé d’un -, le compilateur mdBook l’interprète différemment dans un fichier.md de page et dans SUMMARY.md.

Cas d’une page mdBook

Dans une page, - est interprété comme une alternative à * pour indiquer que le lien est un élément d’une liste.

Ainsi,

- [Texte du lien interne](lien-interne)

affiche ceci :

• Texte du lien interne

Cas du sommaire mdBook

Dans le sommaire mdBook, si le [ est précédé d’un -, il s’agit d’un chapitre de sommaire numéroté.

et s’affiche sous la forme :

1. Texte du lien interne

avec un niveau qui dépendra de son indentation dans SUMMARY.md.

De nombreux éléments non interprétés et non affichés dans SUMMARY.md

En plus d’avoir une interprétation différente pour certains composants, beaucoup de choses ne sont ni interprétées ni affichées dans le projet mdBook compilé si elles sont écrites dans le sommaire mdBook.

Liste de limitations dans le sommaire

• Les titres de rubriques de sommaire ne peuvent être que de niveau 1.
  Il n’est pas possible d’indenter les titres de rubriques du sommaire ni d’indiquer des titres de niveau 2 avec la syntaxe ##.

Liste d’impossibilités dans le sommaire

• Les options de mise en forme du texte ne sont pas prises en compte dans le sommaire mdBook.
• Les paragraphes ne sont pas affichés dans le sommaire mdBook, et donc tout ce qu’un paragraphe contient :
  • un lien brut précédé d’un texte n’est pas affiché.
• Les images ne sont pas affichées dans le sommaire mdBook.
• Les codes isolés ne sont pas affichés dans le sommaire.
• Les blocs de code ne sont pas affichés dans le sommaire mdBook.
• Le contenu d’un fichier.md inséré n’est pas affiché dans le sommaire mdBook.
• Le contenu d’un fichier de code informatique inséré dans un bloc de code n’est pas affiché dans le sommaire mdBook.
• Les liens Web (écrits avec le format <https://(...)>) ne sont pas interprétés correctement par le compilateur mdBook et / ou génèrent des erreurs dans le site produit.
• etc.