Ce bloc-notes mdBook vous est proposé avec passion par Marc JESTIN — Happy Numeric.
À votre service pour vous accompagner dans vos projets numériques.
Contact : https://happynumeric.fr/me-contacter.

mdBook : SUMMARY.md : structurer les pages mdBook

SUMMARY.md est le premier fichier d'un projet mdBook présent dans le dossier source /Nom-du-projet/src (par défaut).

Il comporte les informations du sommaire mdBook.

SUMMARY.md a un rôle particulier : le compilateur mdBook s'appuie sur les informations qu'il contient pour créer des dossiers et des fichiers si ceux-ci n'existent pas.

Important

Il ne faut pas changer le nom du fichier SUMMARY.md ni le déplacer ailleurs que dans le dossier source.

Le fichier comporte une ligne # Summary que je recommande de toujours laisser au tout début du fichier. Voir mdBook : SUMMARY.md : Spécificités.

Organisation et syntaxe

SUMMARY.md a un double rôle :

  • organiser le sommaire mdBook affiché qui facilite le parcours des lecteurs ;
  • organiser et structurer les dossiers et fichiers du projet mdBook.

Il existe deux types de niveaux d'organisation dans le sommaire mdBook :

  • les rubriques du sommaire mdBook et
  • les chapitres du sommaire mdBook qui peuvent être
    • numérotés ou
    • non numérotés.

Rubriques du sommaire mdBook

Les rubriques du sommaire mdBook commencent par un #, par exemple : 

# Titre de rubrique

Exemples ici :

  • Notions de base mdBook
  • Création et édition d'un livre mdBook

Chapitres du sommaire mdBook

Les chapitres du sommaire mdBook sont identifiés par une structure de type :

[Titre du chapitre](lien-interne-vers-le-fichier-markdow-source)

Indentation

L'indentation permet de signaler des sous-chapitres.

Par exemple :

- [Titre de niveau 1]()
	- [Titre de niveau 2]()

Je recommande d'utiliser des tabulations pour réaliser l'indentation.
Voir mdBook : indentation : espaces ou tabulations ?.

Chapitres du sommaire mdBook numérotés

Les chapitres du sommaire mdBook numérotés s'écrivent avec - [ en début de ligne :

- [Titre du chapitre](lien-interne-vers-le-fichier-markdow-source)

Chapitres du sommaire mdBook non numérotés

Les chapitres du sommaire mdBook non numérotés s'écrivent avec [ en début de ligne (sans le -) :

[Titre du chapitre](lien-interne-vers-le-fichier-markdow-source)

Il existe des restrictions dans les positions possibles.
Voir mdBook : SUMMARY.md : Spécificités.

Numérotation des chapitres du sommaire mdBook

La numérotation des titres de chapitres du sommaire mdBook est automatique.

Elle ne tient pas compte de la présence des chapitres de sommaire mdBook non numérotés.

Avec ou sans lien

Nous pouvons créer notre structure de sommaire mdBook sans associer de fichier.md.

Par exemple :

- [Titre de niveau 1]()
	- [Titre de niveau 2]()
		- [Titre de niveau 3]()
		- [Titre de niveau 3]()
	- [Titre de niveau 2]()
	- [Titre de niveau 2]()
- [Titre de niveau 1]()
	- [Titre de niveau 2]()
	- [Titre de niveau 2]()

Cas d'application :

  • crééer et intégrer les fichier.md ensuite progressivement (c'est l'application prévue par la documentation officielle) ;
  • disposer des titres intermédiaires sur leur associer de page mdBook de manière permanente pour structurer notre sommaire mdBook comme je l'ai fait ici.

Exemples de chapitres du sommaire mdBook sans page mdBook associée ici :

  • « mdBook : Contenus particuliers » ;
  • « mdBook : Astuces » .

Liens vers les pages mdBook

Les liens vers les fichiers décrivant les contenus des pages mdBook sont écrits entre parenthèses juste après le crochet fermant du titre de chapitre du sommaire mdBook.

Ces liens peuvent être relatifs ou absolus.

Le compilateur mdBook crée des pages nom-de-fichier.html et conserve les noms des sous-dossiers dans le site mdBook qu'il crée.

Je recommande d'utiliser des noms de dossiers et de fichiers explicites et clairs qui améliorent le référencement naturel Web de nos pages.

Pour l'écriture des liens internes, les mêmes règles que celles décrites dans mdBook : Liens internes : Chemins relatifs s'appliquent.

Création des sous-dossiers et des fichiers fichier.md

Nous pouvons laisser mdBook créer les dossiers et les fichiers en pilotant l'opération depuis le fichier SUMMARY.md.

Nous procédons ainsi :

  • ouverture du fichier SUMMARY.md ;
  • création du titre de chapitre mdBook souhaité, écrit entre crochets [] ;
  • écriture des noms de sous-dossiers (optionnel) et du nom de fichier.md souhaités, écrits entre parenthèses () ;

Si nous nous servons de mdbook serve, il suffit ici d'enregistrer SUMMARY.md et le compilateur mdBook se charge de créer les dossiers et fichiers s'ils n'existent pas déjà.

Sinon, nous pouvons utiliser la commande mdbook build pour le faire.

Nous vérifions avec le gestionnaire de fichiers que tout s'est bien passé, puis nous ouvrons le fichier.md correspondant pour l'éditer.

Vous pouvez soutenir mon travail sous forme de don libre.
Contactez-moi si vous souhaitez entreprendre cette démarche.

De l'importance de structurer notre projet mdBook

Du fait de la logique retenue dans le fonctionnement de mdBook, il n'est pas possible de générer une structure de plan continue par édition progressive comme dans la plupart des traitements de texte par exemple.

Nous devons choisir quel niveau sera du ressort du sommaire mdBook et quel niveau sera de celui des pages mdBook.

Tous ces contenus doivent être édités manuellement et séparément.

Il est donc important de structurer notre projet rapidement et clairement de manière à ne pas avoir besoin de revoir la structure et le contenu des fichiers à la main par la suite.

Soit nous définissons un plan complet dès la phase de construction du projet, soit nous risquons de devoir revoir le plan en profondeur.

Particularités de SUMMARY.md

Il existe de nombreuses différences dans le traitement du fichier SUMMARY.md par le compilateur par rapport à celui des autres fichiers.md du projet.

Voir mdBook : SUMMARY.md : Spécificités.
Ce bloc-notes mdBook vous est proposé par Marc JESTIN — Happy Numeric.
Formation, rédaction de documentations techniques ou organisationnelles, mise en place de solutions documentaires internes et externes, assistance à maîtrise d'ouvrage, etc.
Contact : https://happynumeric.fr/me-contacter

N'hésitez pas à me faire votre feedback, me signaler des erreurs ou des compléments que vous souhaiteriez que j'ajoute à ce bloc-notes mdBook.
Cliquez ici pour me contacter

À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 23 mars 2023 20:43