Introduction

Ce livre est un travail personnel.

J’ai choisi de le publier et de le partager pour « faire ma part ».

La consultation de ce livre est « en don libre ».

Oui, vous pouvez

Si vous souhaitez m’encourager ou m’aider, vous pouvez.

• effectuer un don.
  • Il vous suffit de me contacter, je vous communiquerai mes coordonnées bancaires.
• me proposer un travail rémunéré salarié
  • sédentaire
  • en télétravail
  • ou dans un bureau
    • si ce n’est pas dans une grande agglomération
    • si c’est au Nord de la France (Bretagne, Normandie, Nord)
      • ou plus au Nord (l’Irlande me plairait tout particulièrement)
  • que vous soyez :
    • une entreprise ;
    • une administration ;
    • une association ou
    • un·e particulier·e.

Mes sites concernant Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook

Bonne lecture

Si vous rencontriez des erreurs, si vous souhaitiez suggérer des ajouts, ou pour toute autre démarche constructive et pertinente, n’hésitez pas à me contacter.

Merci.

Marc JESTIN,
éco-citoyen du monde
https://marcjestin.fr

Avertissement

Ce livre mdbook est à l’étape du projet de création et dans son format brouillon (draft) pour le moment.

Il peut comporter des défauts ou des erreurs et sa forme comme son contenu évoluent continuellement.

Merci de votre compréhension.

Si vous souhaitez m’apporter votre soutien ou votre concours pour ce projet, vous pouvez me contacter.

Marc JESTIN
éco-citoyen du monde
https://marcjestin.fr

Conseils de lecture

Ce livre est réalisé avec mdbook, l’outil de documentation de la communauté Rust.

Zoom d’affichage

Les sites web modernes ont la fâcheuse habitude de gaspiller de l’espace disponible et d’user nos organes visuels prématurémement.

Je vous recommande vivement de régler le zoom d’affichage pour un confort optimal.
Niveau de zoom à mon avis confortable :

• 150 % pour un moniteur 1920 x 1080 ;
• 180 % pour un moniteur 2560 x 1440 ;
• 240 % pour un moniteur 3840 x 2160.

Nos yeux et nos oreilles sont précieux (et les dégâts que nous leur causons sont irréversibles) :
PRÉSERVONS-LES !

Lecture à deux niveaux

Vous croiserez parfois des blocs comme celui-ci :

Nota :

• Cliquez sur le bloc « Compléments de lecture (avancés) » pour le développer.
• Cliquez à nouveau pour le réduire.

Utilisation des outils de mdbook

Prenez le temps d’interagir avec les espaces de ce site pour savoir ce que vous pouvez faire :

• parcours facilité
  • « aller à la page suivante dans le livre » (flèche sur le côté droit) ;
  • « revenir à la page précédente dans le livre » (flèche sur le côté gauche) ;
  • Vous pouvez masquer la barre latérale avec le sommaire général si vous choisissez ce type de lecture.
• options de l’interface
  • masquer / afficher la barre latérale (hamburger) ;
  • modifier le thème d’affichage (pinceau) ;
  • rechercher (loupe) ;
    • la recherche est un outil puissant, pensez à vous en servir (voir compléments ci-dessous).
• imprimer
  • vous pouvez produire une version imprimable du contenu de l’ensemble de ce livre (imprimante à droite).
    • que vous pouvez enregistrer au format pdf pour le parcourir hors connexion par exemple.
      • en perdant toutefois toute l’interactivité des blocs de code…

Blocs de codes

Cette partie concerne plus particulièrement les lecteurs·trices des livres relatifs au langage Rust (moins ceux·celles de mon livre au sujet de mdBook lui-même).

mdBook permet de disposer d’un outil avec des blocs de codes Rust interactifs riches.

Tous les blocs de codes sont copiables directement ou avec le bouton ad hoc.

Nous pouvons en plus :

• les éditer (modifier) en nous plaçant dans le code et en supprimant ou saisissant du code ;
  • un bouton permet de remettre le code dans son état d’origine si besoin ;
• les compiler (ou obtenir les messages d’avertissement et d’erreur du compilateur) et / ou
• lorsque c’est prévu pour, observer leurs produits d’exécution affichages.

Lorsque des codes comportent des exemples d’erreurs qui ne passent pas à la compilation, ces parties sont commentées. Décommentez-les, cliquez sur le bouton pour compiler et / ou exécuter, et lisez les retours du compilateur que vous obtenez à l’écran.

Vous pouvez également tout à loisir modifier le code et faire vos propres essais.

Exemple

Exercez-vous avec ce bloc simple :

• retirez les // à gauche de x += 1; puis
• cliquez sur « Run this code » (flèche « play »).
• Cliquez sur le bouton pour rétablir le code (Undo changes) puis
• cliquez sur « Run this code » (flèche « play ») à nouveau.

fn main() {
    let x = 7;
    // x += 1;  // Erreur à la compilation
}

Nota : les boutons interactifs apparaissent

• lorsque nous survolons le bloc de code avec notre souris ou
• lorsque nous touchons l’écran une première fois dans la zone du bloc de code (écrans tactiles de tablettes et d’ordiphones).

Terminologie

J’utilise l’association avec mdBook de manière systématique pour éviter toute confusion.

Les expressions des concepts principaux sont toujours formulés de la même manière pour les mêmes raisons.

Je suppose que nous avons déjà procédé à l’installation de mdBook sur notre ordinateur pour ce qui suit.

Projet mdBook

Un projet mdBook est composé de plusieurs éléments et se construit au travers de ces quelques étapes :

• la création d’un dossier nom-du-projet/ ;
• l’initialisation du projet mdBook dans ce dossier ;
• l’édition d’un fichier de paramètres de compilation mdBook book.toml (si nécessaire) ;
• l’édition d’un fichier SUMMARY.md qui construit le sommaire mdBook ;
• l’édition et le chargement d’un certain nombre de fichiers sources dans un dossier source (src/ par défaut) ;
• la compilation du « livre » par le compilateur mdBook ;
• la publication du site Web mdBook ainsi produit dans le dossier destination du serveur ad hoc.

sommaire mdBook et fichier SUMMARY.md

Un site Web mdBook se présente comme un tout composé :

• d’un sommaire mdBook et
• de pages mdBook indiquées dans ce sommaire mdBook.

Le sommaire mdBook est ce qui permet de générer le contenu qui apparaît à gauche des pages web d’un document mdBook (par défaut).

Le sommaire mdBook donne accès aux différentes pages mdBook qui décrivent le contenu du projet mdBook : textes, images, liens, blocs de citation, blocs de codes, etc.

Le fichier du sommaire mdBook est le fichier SUMMARY.md (par défaut).

SUMMARY.md** se trouve dans le dossier source nom-du-projet/src (par défaut).

SUMMARY.md est interprété et géré différemment des autres fichiers par le compilateur mdBook.

Seuls les fichiers référencés dans SUMMARY.md sont compilés par le compilateur mdBook.

Il ne faut pas renommer le fichier SUMMARY.md ni le déplacer du dossier source.

Pages mdBook et fichiers.md

Une page mdBook est reliée pas un lien interne au sommaire mdBook en tant que chapitre du sommaire mdBook.

Une page mdBook est un composant du site Web mdBook défini dans un fichier fichier.md écrit en langage Markdown.

Le nom des fichiers.md se termine par .md, md faisant référence à MarkDown (le langage utilisé pour écrire et décrire le contenu des pages mdBook).

Les fichiers.md peuvent être stockés dans des sous-dossiers du dossier source tout comme d’autres types de fichiers (images, codes informatiques, etc.).

Organisation du sommaire mdBook

Rubrique du sommaire mdBook

Une rubrique du sommaire mdBook est un titre non numéroté qui permet de compartimenter les chapitres pour en faciliter la lecture.

Une rubique du sommaire mdBook n’est pas associée à une page mdBook : elle ne comporte pas de lien.

Exemples de rubriques du sommaire mdBook ici :

• « Notions de base mdBook » ;
• « Structurer le sommaire mdBook ».

Chapitre du sommaire mdBook

Un chapitre du sommaire mdBook est un titre numéroté ou non dans le sommaire mdBook.

Un chapitre du sommaire mdBook conduit en principe vers une page mdBook associée.

Exemples de chapitres du sommaire mdBook non numérotés ici :

• « Introduction » ;
• « À propos » ;

Exemples de chapitres du sommaire mdBook numérotés ici :

• « mdBook : Concepts et organisation » ;
• « mdBook : SUMMARY.md : structurer les pages mdBook ».

Chapitre du sommaire mdBook sans page mdBook associée

Il est possible de ne pas associer de page mdBook à un chapitre du sommaire mdBook, numéroté ou non.

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

• « mdBook : Mise en forme Markdown » ;
• « mdBook : Les liens ».

Sous-chapitre du sommaire mdBook

Les chapitres du sommaire mdBook peuvent comporter plusieurs niveaux.

Exemples de sous-chapitres du sommaire mdBook ici :

• « mdBook : La compilation » ;
• « mdBook : Markdown : Les images ».

Ces deux exemples sont des sous-chapitres du sommaire mdBook de niveau 2.

Chapitre de page mdBook

Un chapitre de page mdBook ou sous-chapitre de page mdBook est un ensemble indentifié par un titre suivi d’un contenu à l’intérieur d’une page mdBook.

Titre

Nous parlons de titre dans ce document pour parler indifféremment des titres de :

• rubriques du sommaire mdBook ;
• chapitres du sommaire mdBook ;
• chapitres de page mdBook.

Le plan du projet mdBook est constitué par l’ensemble de ces titres (voir Table des matières ci-dessous).

Table des matières

Bien que la documentation officielle et les infobulles des sites Web mdBook parlent de « Table of Contents », j’évite le terme table des matières.

En effet, le sommaire mdBook ne contient pas tous les titres et sous-titres d’un document mdBook. Les sous-niveaux définis dans les pages mdBook n’y figurent pas nécessairement (en fonction des options).

Il n’existe pas de Table des matières complète statique à proprement parler dans un site Web mdBook.

Conventions

Lorsque nous nous lançons dans la création d’un projet mdBook, il est préférable d’appliquer des conventions afin d’augmenter notre productivité et d’améliorer la lisibilité de nos supports.

Il existe plusieurs conventions qui sont importantes au premier rang desquelles :

• les conventions d’écriture ;
• les conventions de nommage ;
• les conventions de codage ;

Conventions d’écriture

Je m’attache à toujours utiliser des expressions explicites dans ma rédaction.

Je pourrais écrire des mots simples isolés comme « page » et supposer que le lecteur comprend, en fonction du contexte, s’il s’agit d’une page mdBook c’est-à-dire d’une page composée avec mdBook ou s’il s’agit d’une simple page Web.
Je pense qu’il est préférable d’être explicite pour que les choses soient plus claires et ne prêtent pas à erreur d’interprétation.

Je m’attache à utiliser toujours la même expression pour le même concept.

Je pourrais écrire à un endroit projet mdBook et plus loin « document » ou « guide » en parlant de ce même projet mdBook.
Je pense qu’il est préférable d’écrire ainsi pour une meilleure lisibilité du texte et pour la bonne interprétation et assimilation des concepts clefs.

J’écris les codes sources et les objets informatiques en tant que codes.

Cela inclut les noms de dossiers et les noms de fichiers : SUMMARY.md, book.toml ou encore nom-du-projet/src.

Cela inclut les caractères isolés qui sont utilisés dans le code en langage Markdown, par exemple ` ou *.

J’écris les mots anglais en caractères italiques ou en gras italique lorsqu’il s’agit de concepts importants.

Je prends soin d’écrire les mots toujours dans le même format.

C’est le cas par exemple de Markdown et de mdBook.

Ces manières d’écrire sont des choix arbitraires.
J’aurais pu choisir d’écrire « MarkDown », j’ai choisi Markdown.
J’aurais pu écrire « mdbook » ou « MDBOOK », j’ai choisi mdBook.

Notons au passage que Markdown est un nom propre.
Je tiens à mettre des lettres majuscules aux premières lettres des noms propres, en accord avec la typographie française.

La règle peut être différente dans les conventions de nommage ou des conventions de codage, si mdbook doit être écrit ainsi dans un fichier de configuration par exemple.

Je respecte ma convention de nommage des dossiers et des fichiers dans les exemples que j’écris.

Je respecte les règles de la typographie française.

Nous utilisons le caractère espace insécable qui est très important en typographie française.
C’est lui qui évite qu’un guillemet fermant ou qu’un signe de ponctuation soit écrit en début de ligne suivante par exemple.

fn main() {
    println("Prénom : Marc");
    // Exemple d'espaces insécables à la place d'espaces.
}

Conventions de nommage

Les conventions de nommage concernent les différents objets qui sont manipulés en développement.

Dans le cadre d’un projet mdBook, cela se résume à convenir de règles pour donner des noms à :

• des dossiers :
  • le dossier du projet mdBook lui-même ;
  • les différents sous-dossiers du dossier nom-du-projet/src (par défaut) ;
• des fichiers :
  • fichiers.md ;
  • images ;
  • codes-sources.rs ;
  • etc.

Ces conventions de nommage peuvent préciser les règles qui s’appliquent pour le classement d’un certain nombre de fichiers et de dossiers, le nom complet étant par exemple :

nom-du-projet/NomDeLaRubriqueDuSommaireMdbook/nom-de-la-page-mdbook.md

Bien entendu, ces conventions de nommage prennent en considération les règles de fonctionnement de mdBook.

Pour ma part, j’ai choisi :

• règles applicable à tous
  • tous les mots sont reliés par un - ;
  • les caractères français sont remplacés, par exemple le é par un e ou le ç par un c.
• pour le dossier du projet mdBook :
  • lettres capitales ou majuscules autorisées ;
  • respect de la majuscule au nom propre (Rust par exemple) ;
  • respect de la convention d’écriture pour mdBook.
• pour tous les autres dossiers et fichiers :
  • lettres minuscules, quel que soit le contexte.
• début du nom des fichiers.md : ils commencent toujours par mdbook (en minuscules, par application de la règle associée), tout comme leur titre.
• début du nom des fichiers.md des chapitres du sommaire mdBook non numérotés du début du sommaire mdBook : mdbook-bloc-notes.

Petite anecdote au sujet des conventions de nommage

J’ai choisi de ne pas utiliser des caractères accentués.
C’est un choix qui pouvait coûter cher et qui peut encore coûter cher en développement et la plupart des développeurs savent qu’il vaut mieux ne pas sortir des codes ASCII de base.

Plus tôt dans ma jeunesse, j’ai un jour travaillé à développer un code informatique dans un environnement bureautique. Le développement en lui-même n’était pas complexe mais des suites d’un choix de nommage d’un des dossiers, le comportement de mon code semblait TOTALEMENT ALÉATOIRE !!!

Cela m’a fait perdre beaucoup de temps et m’a causé beaucoup de tracas inutiles.

En conclusions :

1. ne sous-estimons jamais l’impact de ce qui peut ressembler de loin à des détails tatillons ;
2. ici l’enjeu est faible, mais il importe de toujours être bien conscient·e·s de toutes les conséquences de tel ou tel choix que nous faisons.

Conventions de codage

Lorsque nous travaillons sur nos conventions de codage, nous devons au préalable bien connaître et maîtriser les conventions du langage spécifique que nous utilisons.

C’est la raison pour laquelle je me suis appuyé principalement sur la documentation officielle mdBook afin de produire le code source de ce « livre ».

Le langage Markdown dispose d’un certains nombres de possibilités afin de réaliser les mêmes choses.

Par exemple, nous pouvons utiliser soit * soit - pour identifier un élément d’une liste.

Ici, le choix a été simple : il m’a été dicté par la documentation officielle mdBook qui propose d’utiliser le *.

Il est préférable d’inclure cette convention de codage dans notre référentiel afin de nous en souvenir et de l’appliquer de manière homogène.

Bien que mdBook s’appuie sur le langage Markdown, il est possible que le compilateur mdBook se comporte différemment d’un autre compilateur dans un autre environnement. Appliquer les mêmes conventions dès le début et pour tous nos projets nous préserve de mauvaises surprises.

mdBook : Architecture des fichiers

Un projet mdBook se crée et vit sa vie dans un dossier local.

Lorsque nous validons la commande suivante en étant dans le dossier nom-du-projet/

mdbook init

et que nous répondons y à la première question (création d’un fichier .gitignore), mdBook crée une base de fichiers dans notre dossier nom-du-projet/.

Le fichier de description et de paramétrage de notre projet mdBook est book.toml.

Les fichiers de création de contenu sont dans le dossier nom-du-projet/src (par défaut).
C’est dans ce fichier book.toml que nous pouvons indiquer un autre emplacement si nous le souhaitons.

Lorsque, en étant dans le dossier nom-du-projet/, nous construisons les fichiers destination avec la commande :

mdbook build

mdBook crée l’ensemble des fichiers et dossiers nécessaires à construction du site Web mdBook dans le dossier nom-du-projet/book (par défaut).

Chargement du site sur un serveur externe

Si nous disposons d’un serveur Web externe, il suffit de copier le contenu du dossier nom-du-projet/book dans un dossier correspondant à l’adresse que nous souhaitons donner à notre site Web mdBook.

Voilà pour le fonctionnement de base de mdBook.

Cela suffit pour créer un projet mdBook sur notre machine et le mettre en ligne sur le World Wide Web.

mdBook : la compilation (build)

mdBook fonctionne sur un principe de compilation (build en anglais).

Le compilateur mdBook (mdBook builder) analyse et interprète les fichiers sources mdBook pour construire un site Web mdBook.

Pour voir le résultat d’un travail d’écriture, il nous faut effectuer une compilation via la commande :

mdbook build

Nous lançons cette commande depuis un Terminal en étant dans le dossier nom-du-projet/.

mdBook utilise notamment le fichier book.toml ainsi que le contenu du dossier source afin de créer le site mdBook dans le dossier destination.

Le dossier source est le dossier nom-du-projet/src (par défaut).

Le dossier destination est le dossier nom-du-projet/book (par défaut).

Mise en garde importante

Le compilateur mdBook efface et recrée l’ensemble des fichiers et sous-dossiers destinations à chaque compilation.

Nous n’avons pas à intervenir dans le dossier nom-du-projet/book.

Si nous souhaitons ajouter des fichiers au site Web mdBook, nous le faisons dans le dossier source.

Voir les méthodes décrites dans :

• mdBook : Markdown : Insertion d’images ;
• mdBook : Insérer un contenu dans une page mdBook.

Autres usages du compilateur

Le compilateur crée les sous-dossiers et fichiers.md définis dans SUMMARY.md et dans les pages mdBook s’ils n’existent pas.

mdBook : Page Accueil

La page Accueil d’un site Web mdBook est la première page mdBook disponible dans le sommaire mdBook du site mdBook.

Par exemple lorsque nous ouvrons l’adresse Web de ce livre,

https://apprendre-et-maitriser-mdbook.marcjestin.fr

la page mdBook qui s’affiche est :

https://apprendre-et-maitriser-mdbook.marcjestin.fr/introduction.html.

qui correspond au premier chapitre du sommaire mdBook : « Introduction ».

Nous pouvons nous servir de la première page mdBook du sommaire mdBook pour créer :

• une page comme nous avons l’habitude de faire des pages Accueil sur des sites Web ;
• une première de couverture comme pour un livre ;
• une page de présentation comme j’ai choisi de le faire ;
• etc.

Créer une page Accueil

Nous pouvons créer une page Accueil si nous le souhaitons.

Il suffit d’ajouter un premier chapitre mdBook (généralement non-numéroté) au fichier SUMMARY.md.

Nous lui donnons le titre « Accueil » et nous l’associons avec une page mdBook que nous composons comme nous le souhaitons.

Par exemple :

[Accueil](/.accueil.md)

Ne pas créer de page Accueil

Nous pouvons ne pas créer de page Accueil.

La page envoyé au lecteur est la première page mdBook figurant dans le sommaire mdBook.

Index.html

Il existe bien un fichier index.html dans la structure des fichiers du site mdBook.

C’est ce que nous avons coutume d’appeler la page Accueil dans un site Web car c’est la page qui s’affiche par défaut si aucune adresse de page Web n’est indiquée.

Ce fichier index.html se charge d’afficher la première page mdBook du sommaire mdBook dans le navigateur web du visiteur.

Risque de conflit ?

Si nous choisissons de créer une page Accueil en utilisant le nom index.md, comme ici :

[Accueil](./index.md)

mdBook le gère sans que cela ne crée de conflit avec son propre fichier index.html.

mdbook serve : visualiser nos modifications en continu

mdBook propose un outil qui fournit un service pour visualiser nos modifications en continu sur notre machine de travail : mdbook serve.

mdbook serve :

• surveille nos modifications des fichiers.md (lorsque nous les enregistrons) ;
• fournit un serveur Web intégré (d’où son nom) ;
• affiche automatiquement la nouvelle version des pages mdbook ouvertes dans notre navigateur web si des modifications ont été enregistrées sans que nous ayons besoin de faire quoique ce soit.

Commande de base

La commande de base, à saisir dans le dossier nom-du-projet/ est :

mdbook serve

Par défaut, nous accédons au serveur Web intégré correspondant en nous rendant à l’adresse :

http://localhost:3000 # pas de https bien sûr, et c'est inutile

Commande avec ouverture du navigateur web

L’option --open ou simplement -o ouvre la visualisation du livre dans notre navigateur web par défaut :

mdbook serve -o

Indiquer un autre port

En cas de besoin, nous pouvons travailler sur un autre port grâce à l’option -p numdeport, par exemple :

mdbook serve -o -p 5555

Est-il obligatoire d’utiliser mdbook serve ?

Nous pouvons ne pas utiliser mdbook serve.

Nous utilisons alors la commande :

mdbook build

pour compiler notre projet mdBook.

Nous pouvons alors visualiser un aperçu du site Web mdBook en ouvrant les fichiers du dossier nom-du-projet/book (par défaut) dans notre navigateur web.

Certains composants ne fonctionnent pas comme dans la version web de notre projet mdBook.

C’est bien plus pratique avec mdbook serve qui nous fait gagner beaucoup de temps, surtout si nous savons écrire et utiliser des scripts.

Assistance apportée par mdbook serve

Lorsque nous faisons tourner mdbook serve, celui-ci effectue certaines tâches automatiquement pour nous.

mdbook serve se charge notamment de créer, lorsqu’ils n’existent pas, les fichiers.md que nous avons définis dans le SUMMARY.md. Si nécessaire, mdbook serve crée la structure de dossiers que nous y avons définie.

Par exemple, si nous ajoutons ceci dans SUMMARY.md (et que les dossiers et fichiers n’existent pas déjà) :

#![allow(unused)]
fn main() {
- [Comment faire](./comment-faire/introduction.md)
  - [Première étape](./comment-faire/premiere-etape.md)
    - [Préambule](./comment-faire/premiere-etape/preambule.md)
}

mdbook serve se charge automatiquement, dès l’enregistrement du fichier sommaire,

• de créer les dossiers, sous-dossiers et fichiers et
• d’insérer les titres de niveau 1 dans les fichiers soit
  • # Comment faire dans le fichier introduction.md,
  • # Première étape dans premiere-etape.md et
  • # Préambule dans preambule.md.

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.

Si nous travaillons, comme il est recommandé, en faisant tourner mdbook serve en tâche de fond, il est important de définir les dossiers et fichiers dans SUMMARY.md et non « à la main » dans l’EDI ou dans le gestionnaire de fichiers.

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 qu’il convient de laisser en l’état 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
• Structurer le sommaire 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.

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.

mdBook : Markdown : choses à savoir

Saut de ligne

Dans le langage Markdown, le fait d’écrire deux lignes l’une à la suite de l’autre est interprété comme une continuité.

Le code :

Ligne 1.
Ce que je crois être la ligne 2.

affiche :

Ligne 1. Ce que je crois être la ligne 2.

Le compilateur mdBook ajoute une espace entre les deux blocs de texte et les écrit l’un à la suite de l’autre sur la même ligne.

Pour écrire un saut de ligne en langage Markdown, nous ajoutons deux espaces ( ) à la fin de la ligne et nous passons effectivement à la ligne.

Ligne 1.  
Ligne 2.

où j’ai bien mis deux espaces à la fin de la ligne 1, que vous pouvez voir en sélectionnant les deux lignes, affiche :

Ligne 1.
Ligne 2.

Espaces multiples

Le compilateur mdBook « arrange » parfois notre texte : si nous écrivons plus d’une espace entre plusieurs mots, il va corriger.

Par exemple, si j’écris :

Ceci            est           un           texte.

Le résultat affiché sera :

Ceci est un texte.

Soulignement et titres

Si j’écris :

Texte
=====

en croyant avoir souligné le texte, le compilateur mdBook crée un chapitre de page mdBook de niveau 1 car c’est la syntaxe Markdown pour le faire.

Texte

Le soulignement de texte n’existe pas en langage Markdown sauf pour l’affichage des liens web en fonction des paramètres des feuilles de style (c’est en réalité en HTML / CSS que ce soulignement intervient, pas dans Markdown à proprement parler).

Par défaut, mdBook n’affiche pas de soulignement pour les liens web, il sont simplement affichés avec une couleur particulière.
Lorsque nous passons la souris sur un lien Web, le soulignement apparaît.
C’est un paramétrage dans les feuilles de style choisi par mdBook.

Syntaxe et séparateurs

Il convient de respecter strictement la syntaxe du langage Markdown.

Les codes qui encadrent un texte doivent être collés au texte en question.

L’espace peut être interprété comme un séparateur et non comme un caractère espace. Ce point est abordé à un endroit que je vous laisse découvrir le moment venu dans ce livre.

La ligne vide est un séparateur dans le langage Markdown. Il ne faut pas, par exemple, insérer de ligne vide dans un même tableau.

Soyons bien attentifs à la syntaxe proposée dans les exemples de ce livre et… Restons vigilant·e·s !

mdBook : Markdown : mise en garde

Il peut exister des variantes dans les langages Markdown.

Je ne les présente pas toutes ici.

Markdown par défaut

Je recommande de nous attacher à utiliser les codes recommandés par mdBook lorsque nous travaillons avec mdBook.

Dans sa documentation officielle, mdBook renvoie vers la « GitHub Flavored Markdown Spec » (spécification Markdown saveur Github) ¹.

À ce jour (20 mars 2023), il s’agit de la v 0.29 gfm (2019-04-06).

Cela ne garantit en rien que le compilateur mdBook est 100 % compatible avec l’intégralité de ce document.

Il est préférable de nous en tenir aux codes et méthodes documentés dans la documentation officielle pour ne pas nous exposer à d’éventuelles difficultés par la suite lors d’une montée de version par exemple.

En effet, la plupart des tests fonctionnels qui sont faits le sont d’abord et avant tout avec les pratiques de la communauté mdBook.

Il est bon d’avoir connaissance des conventions et pratiques autres, mais nous devrions avoir conscience et nous attacher à nous en tenir à celles de l’outil.

J’ai créé ce livre en me référant aux documentations et autres supports mdBook officiels.

Vous ne devriez pas rencontrer de difficultés particulières si vous suivez les indications que j’y donne.

Rester homogène

Lorsque plusieurs symboles sont possibles, le fait de les mélanger n’est pas une bonne idée.

Si nous écrivons nos fichiers sources en mélangeant les symboles, nous risquons d’obtenir de mauvais résultats ou de perdre des contenus dans le projet mdBook une fois compilé.

Par exemple, avec ce type d’écriture :

- [mdBook : Fonctions avancées]()
	- [mdBook : serve : visualiser nos modifications en continu](./mdbook-serve-visualiser-nos-modifications-en-continu.md)
	* [mdBook : renommage d'une page](./mdbook-renommage-d-une-page.md)

le compilateur mdBook génère un sommaire qui élude un des deux sous-chapitres de sommaire mdBook.

Dommage !

En principe, nous n’avons pas de problème si nous définissons correctement et respectons des conventions de codage.

Ces Conventions de codage devraient être rédigées par des personnes compétentes de manière suffisamment claire pour être appliquées à la lettre et sans le moindre malentendu par des personnes moins expertes.

1. GitHub Flavored Markdown Spec (anglais) : https://github.github.com/gfm/ ↩

mdBook : Markdown : mise en forme des caractères

La mise en forme est gérée par l’encadrement des zones souhaitées par un élément de code composé d’un ou plusieurs caractères dans la syntaxe du langage Markdown.

Mettre en italique

Il suffit de mettre un astérisque * avant et après un texte pour qu’il soit affiché en italiques.

Par exemple :

« Le mot *italique* est écrit en *italiques*. »

affiche :

« Le mot italique est écrit en italiques. »

Mettre en gras

Les deux astérisques ** qui l’encadrent (ou les encadrent) indiquent un (ou plusieurs) caractère(s) en gras.

Par exemple :

« Le mot **gras** est écrit en **gras**. »

affiche :

« Le mot gras est écrit en gras. »

Mettre en gras italique

Pour mettre un texte en gras italique, nous l’encadrons de trois astérisques ***.

Par exemple :

« Les mots ***gras et italique*** sont écrits en ***gras italiques***. »

affiche :

« Les mots gras et italique sont écrits en gras italiques. »

Barrer

Le double tilde ~~ encadre un texte barré.

Par exemple :

« Le mot ~~barré~~ est ~~barré~~. »

affiche :

« Le mot barré est barré. »

Souligner du texte

Markdown ne permet pas de souligner du texte.

En Markdown, le soulignement juste en dessous du texte dans le fichier source produit un titre :

• un ou plusieurs = pour un titre de niveau 1 ;
• un ou plusieurs - pour un titre de niveau 2.

Cette syntaxe n’est pas instruite dans la documentation officielle de mdBook.

En effet, dans les fichiers.md (hors sommaire mdBook) nous utilisons :

• # en début de ligne suivi d’une espace pour un écrire un titre de niveau 1 ;
• ## en début de ligne suivi d’une espace pour écrire un titre de niveau 2 ;
• et ainsi de suite jusqu’au niveau 6 inclus.

Des combinaisons sont possibles

Des combinaisons sont possibles.

Par exemple, il est possible de mettre un code en gras comme lorsque j’écris fichiers.md.

Pour ce faire, j’ai écrit ceci dans le fichier source de cette page mdBook :

**`fichiers.md`**

Dans les combinaisons, la hiérarchie et la logique s’appliquent

Les caractères écrits le plus à l’extérieur sont interprétés en premier.

Cette écriture :

`**fichiers.md**`

produit :

**fichiers.md**

et c’est logique : comme j’ai indiqué au compilateur mdBook qu’il doit afficher un texte (ici **fichier.md**) en tant que code, le compilateur mdBook ne cherche pas à interpréter les ** à l’intérieur du code en question, il les affiche en tant que parties du code, comme demandé.

Attention, il peut exister des exceptions à la logique : c’est le cas avec la consigne include de mdBook lorsqu’elle est écrite dans un bloc de code.
J’aborde ce point dans la page appropriée de ce livre.

mdBook : Markdown : Ligne horizontale

Pour insérer une ligne horizontale, il convient d’ajouter

---

au début d’une ligne à l’endroit souhaité.

La Ligne horizontale occupe tout l’espace de la zone de texte.

Par exemple :

Ceci est mon texte

---

affiche

Ceci est mon texte

Avec des listes indentées :

Code markdown :

* Liste de niveau 1
	* Liste de niveau 2

---

Résultat affiché :

• Liste de niveau 1
  • Liste de niveau 2

Le trait horizontal commence bien à gauche de la zone de texte.

Respecter le saut de ligne

Attention de bien séparer l’indication de ligne horizontale (---) de la ligne de texte qui la précède avec une ligne vide.

Le fait d’oublier le saut de ligne peut avoir des conséquences liées au langage Markdown.

Par exemple :

Ceci est mon texte
---

affiche :

Ceci est mon texte

car le soulignement est interprété comme étant un indication de titre par le compilateur mdBook.
En effet, le fait d’insérer un (ou plusieurs) trait(s) - directement dans la ligne sous un texte est interprété comme une indication de titre de niveau 2 dans le langage Markdown.

Tout n’est pas possible

Certaines présentations ne produisent pas ce qu’une analyse humaine peut imaginer lorsque nous travaillons en langage Markdown.

Par exemple :

---

* liste 1

---

	* liste 2

---

affiche :

• liste 1

* liste 2

Le * n’est pas interprété comme une liste pour liste 2, non pas à cause des lignes horizontales, mais du fait de l’isolement de la ligne.

Lorsqu’il analyse cette syntaxe, le compilateur mdBook voit une ligne isolée commençant par une tabulation, ce qui signifie pour lui qu’il s’agit d’un bloc de code.
En effet, la tabulation est une alternative aux ``` sur les lignes avant et après le contenu pour définir un bloc de code en langage Markdown.

Cas particulier de SUMMARY.md

Le compilateur mdBook crée un affichage de cette ligne horizontale en fonction de la ligne (de contenu) qui la précède dans SUMMARY.md

Comme nous pouvons le voir ici :

La ligne horizontale démarre son côté gauche à hauteur du paragraphe qui la précède.

Le code correspondant dans le fichier source SUMMARY.md est :

Je pense que nous pouvons considérer ce décalage lié à l’indentation comme un bogue.

Trois traits ou plus

Le compilateur mdBook crée une ligne horizontale à partir de trois traits -.

Il interprète tout nombre de traits - supérieur ou égal à trois comme une seule et même ligne.

De même s’il y a un ou plusieurs espaces et un ou plusieurs ensembles continus de traits : le compilateur mdBook ne crée qu’une seule ligne dans le site Web mdBook produit.

mdBook : Markdown : Chapitres de pages mdBook

Le rôle particulier du sommaire mdBook

Le sommaire mdBook est le contenu du fichier spécial SUMMARY.md où nous définissons et organisons les rubriques du sommaire mdBook et des chapitres du sommaire mdBook.
Voir Terminologie.

Il convient de commencer par travailler le plan de notre document au niveau du sommaire mdBook.

Il est ensuite possible de créer des chapitres dans chaque chaque page mdBook.

Nous les appelons chapitres de page mdBook pour les distinguer des chapitres du sommaire mdBook.

Les chapitres de page mdBook ne sont pas affichés dans le sommaire mdBook mais servent à articuler et organiser les contenus de nos pages mdBook.

Chapitres de page mdBook

La présence de caractère(s) # (suivis d’au moins une espace) en début de ligne indique au compilateur mdBook qu’il s’agit d’un chapitre de page mdBook.

Alors que # est associé aux rubriques du sommaire mdBook dans le sommaire mdBook, il sert à indiquer des chapitres de page mdBook dans les pages mdBook.

Niveau des chapitres de page mdBook

mdBook copie le titre de chapitre du sommaire mdBook de la page mdBook au début du fichier.md lorsqu’il le crée.

mdBook lui associe un # qui indique un titre de niveau 1.

Nous utilisons donc des titres de niveau 2 minimum pour les chapitres de page mdBook pour tenir compte de cette convention, le niveau 1 étant réservé aux titres de chapitre du sommaire mdBook dans les fichiers.md.

Nous écrivons :

## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5

pour afficher :

Titre de niveau 2

Titre de niveau 3

Titre de niveau 4

Titre de niveau 5

mdBook : Markdown : Les listes

Les listes (non numérotées)

Le caractère Markdown pour identifier une liste est le * placé en début de ligne (et suivi d’au moins une espace).

Note : Le - fonctionne également en langage Markdown et dans mdBook.

L’indentation permet de signaler des sous-niveaux de listes.

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

Exemple de liste avec des sous-niveaux :

* liste de niveau 1
	* liste de niveau 2
		* liste de niveau 3
			* liste de niveau 4
	* liste de niveau 2
* liste de niveau 1
	* liste de niveau 2

affiche :

• liste de niveau 1
  • liste de niveau 2
    • liste de niveau 3
      • liste de niveau 4
  • liste de niveau 2
• liste de niveau 1
  • liste de niveau 2

Les listes numérotées

Le caractère Markdown pour identifier une liste numérotée est 1. placé en début de ligne (et suivi d’au moins une espace).

L’indentation permet de signaler des sous-niveaux de listes numérotées.

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

Exemple de liste numérotée avec des sous-niveaux :

1. liste de niveau 1
	1. liste de niveau 2
		1. liste de niveau 3
			1. liste de niveau 4
	1. liste de niveau 2
1. liste de niveau 1
	1. liste de niveau 2

affiche :

1. liste de niveau 1
   1. liste de niveau 2
      1. liste de niveau 3
         1. liste de niveau 4
   2. liste de niveau 2
2. liste de niveau 1
   1. liste de niveau 2

Listes mixtes numérotées ou non

Il est possible de mixer des listes numérotées et des listes (non numérotées).

Exemple :

1. liste de niveau 1
	1. liste de niveau 2
		1. liste de niveau 3
			1. liste de niveau 4
			* niveau 1 de la liste non numérotée 1
			* niveau 1 de la liste non numérotée 1
				* niveau 2 de la liste non numérotée 1
	1. liste de niveau 2
	* niveau 1 de la liste non numérotée 2
		* niveau 2 de la liste non numérotée 2
			* niveau 3 de la liste non numérotée 2
	* niveau 1 de la liste non numérotée 2
1. liste de niveau 1
	1. liste de niveau 2

affiche :

1. liste de niveau 1
   1. liste de niveau 2
      1. liste de niveau 3
         1. liste de niveau 4
         • niveau 1 de la liste non numérotée 1
         • niveau 1 de la liste non numérotée 1
           • niveau 2 de la liste non numérotée 1
   2. liste de niveau 2
   • niveau 1 de la liste non numérotée 2
     • niveau 2 de la liste non numérotée 2
       • niveau 3 de la liste non numérotée 2
   • niveau 1 de la liste non numérotée 2
2. liste de niveau 1
   1. liste de niveau 2

Respect de la logique d’indentation

L’interpréteur ne sait pas gérer des décalages de plus de 1 niveau en descendant dans les sous-niveaux.

C’est tout à fait normal si on reprend la logique de la structure des niveaux et sous-niveaux de listes : Un élément de liste de niveau N+1 est nécessairement consécutif à un élément de liste de niveau N.

Si nous faisons une erreur, le compilateur mdBook n’interprète pas l’élément de liste de niveau inférieur décalé et l’ajoute à la suite de l’élément de liste en cours.

Par exemple :

1. liste de niveau 1
	1. liste de niveau 2
		1. liste de niveau 3
			1. liste de niveau 4
	1. liste de niveau 2
1. liste de niveau 1
			1. liste de niveau 4

affiche :

1. liste de niveau 1
   1. liste de niveau 2
      1. liste de niveau 3
         1. liste de niveau 4
   2. liste de niveau 2
2. liste de niveau 1 1. liste de niveau 4

Dans l’exemple ci-dessus, un éléments de liste de niveau 4 succède directement à un élément de liste de niveau 1, ce qui n’est pas possible. Le « 1. » est alors traité comme un élément du texte « 1. liste de niveau 4 ». La présence de plusieurs tabulations est simplement ignorée.

mdBook : Markdown : les tableaux

La création des tableaux en langage Markdown est simple.

Les caractères | encadrent les contenus des colonnes de tableau.

Le fait d’insérer une ligne de type |-|-|-| en dessous de la première ligne de tableau permet d’indiquer au compilateur mdBook qu’il s’agit d’un tableau.

La largeur des colonnes de tableau est ajustée automatiquement aux contenus en appliquant des règles de proportionnalité en cas d’atteinte des limites de largeur.

Par exemple :

|Colonne 1|Colonne 2|Colonne 3|
|-|-|-|
|Contenu 1|Contenu 2|Contenu long 3|
|Contenu 1|Court 2|Contenu 3|
|Contenu 1|Contenu 2|Contenu 3|

affiche :

Autre exemple :

|Colonne 1||Colonne 3|
|--------------|-----------|------------|
|Contenu 1|l1|Contenu long 3 mais pas trop long|
|Contenu 1|l2|Contenu 3|
|Contenu vraiment très très très long et d'ailleurs on se demande jusqu'où il va aller 1|l3|Contenu 3|

affiche :

Effet d’un retour à la ligne

Le retour à la ligne est interprété par le compilateur mdBook comme un passage à la ligne suivante du tableau.

Par exemple :

|Mon tableau|
|-|
|Ceci est une ligne
Ceci est une nouvelle ligne|

affiche :

Optimisations d’écriture

Les | sont optionnels s’il nous n’avons plus de texte ou de données à saisir dans les colonnes plus à droite.

Si nous n’avons que la première colonne (de gauche) à compléter avec du texte, le | de début de ligne de tableau est également optionnel.

Par exemple (nous éludons tous les | à droite du dernier texte à écrire) :

|Colonne 1|Colonne 2|Colonne 3
|-|-|-|
|Contenu 1|Contenu 2
|Contenu 1
|Contenu 1|Contenu 2|Contenu 3

affiche :

Ou encore (sans le | de gauche pour la ligne avec un seul contenu) :

|Colonne 1|Colonne 2|Colonne 3
|-|-|-|
|Contenu 1|Contenu 2
Contenu 1
|Contenu 1|Contenu 2|Contenu 3

affiche :

Je recommande d’écrire les tableaux « rigoureusement » pour une meilleure lisibilité, c’est-à-dire sans éluder les |.

Laisser la première ligne vide

Nous pouvons laisser la première ligne du tableau vide en écrivant cette ligne comme ceci : |||| (sans éluder les séparateurs de colonnes de tableau |).

Ce code

||||
|--------------|-----------|------------|
|Contenu 1|l1|Contenu long 3 mais pas trop long|
|Contenu 1|l2|Contenu 3|
|Contenu vraiment très très très long et d'ailleurs on se demande jusqu'où il va aller 1|l3|Contenu 3|

s’affiche sous cette forme :

Changer la présentation d’un tableau

La manière dont le tableau s’affiche est gérée au niveau des feuilles de style du thème de notre projet mdBook.

Cela relève d’un niveau de compétences et de maîtrise que nous abordons dans d’autres pages mdBook de ce livre.

mdBook : Markdown : Codes dans le texte

Le caractère ` est obtenu avec la combinaison de touches AltGr + 7.

Pour insérer du code à l’intérieur d’un paragraphe, nous encadrons le texte du code avec le caractère `.

Exemple :

Ceci est un texte avec un `code`.

affiche :

Ceci est un texte avec un code.

Cas d’un code avec un ` à l’intérieur

Si nous avons besoin d’insérer un code qui, lui-même, comporte un caractère ` à l’intérieur, nous doublons celui-ci : ``.

Exemple :

Ceci est un texte avec un ``code qui comporte un `mot` encadré`` par le caractère `` ` ``.

affiche :

Ceci est un texte avec un code qui comporte un `mot` encadré par le caractère `.

Mettre une espace interprétée comme séparateur

Dans `` ` ``  l’espace sert de séparateur pour permettre au compilateur mdBook de comprendre comment interpréter la série de `.

Si nous les écrivons tous à la suite sans espace, le compilateur voit un seul token (au sens du langage informatique) et la page mdBook produite affiche ceci : `````.

Si nous écrivons `` ` `` , nous indiquons, grâce à l’espace (qui sert ici de séparateur et non en tant que caractère à afficher) au compilateur mdBook qu’il doit « voir » : `` suivi de ` suivi de ``.
Le compilateur mdBook comprend alors ce que nous souhaitons faire et l’interprète correctement pour afficher ` comme souhaité.

mdBook : Markdown : Blocs de citations

Pour écrire un bloc de citation, il suffit de mettre le caractère « > » en début de ligne.

Par exemple :

> « Ceci est une citation. »

affiche :

« Ceci est une citation. »

Pour écrire plusieurs lignes nous pouvons utiliser les deux espaces en fin de ligne ( ) pour ajouter un saut de ligne :

> « Ceci est une citation  
très longue  
sur plusieurs lignes. »

qui produit :

« Ceci est une citation
très longue
sur plusieurs lignes. »

Pour écrire plusieurs paragraphes dans le même bloc de citation, nous écrivons :

> « Ceci est une citation...
>
> Qui comporte plusieurs paragraphes. »

ce qui affiche après compilation :

« Ceci est une citation…

Qui comporte plusieurs paragraphes. »

Pour séparer deux blocs de citation l’un à la suite de l’autre, nous insérons une ligne vide entre les deux :

> « Ceci est la citation 1.»

> « Ceci est la citation 2.»

donne :

« Ceci est la citation 1. »

« Ceci est la citation 2. »

Pour ajouter l’auteur d’une citation, nous l’ajoutons dans le bloc en dehors des guillemets (note : il y a deux espaces après la première ligne pour ajouter un saut de ligne) :

> « Je ferai les images plus tard quand j'aurai le temps. »  
> — Alfred EINSTEIN

ce qui produit :

« Je ferai les images plus tard quand j’aurai le temps. »
— Alfred EINSTEIN

> Ceci est un bloc de citation.

>Ceci est un bloc de citation.

mdBook : Markdown : Blocs de codes

Le caractère ` est obtenu avec la combinaison de touches AltGr + 7.

Pour insérer un bloc de code, le langage Markdown propose d’utiliser ``` pour identifier le début et la fin du bloc de code.

Les délimiteurs sont placés sur la ligne au-dessus et la ligne en dessous du contenu du bloc de code.

Par exemple :

```
> « Ceci est une citation. »
```

affiche :

> « Ceci est une citation. »

Nous pouvons indiquer le langage utilisé dans le bloc code (pour la mise en relief des éléments syntaxiques, réalisée par highlight.js).

C’est le cas ici :

```rust
# fn main() {
# use log::{debug, trace, warn};
# use serde::{Deserialize, Deserializer, Serialize, Serializer};
# use std::collections::HashMap;
# use std::env;
# use std::fs::File;
# use std::io::Read;
# use std::path::{Path, PathBuf};
# use std::str::FromStr;
# use toml::value::Table;
# use toml::{self, Value};
#
# use crate::errors::*;
# use crate::utils::{self, toml_ext::TomlExt};
#
/// The overall configuration object for MDBook, essentially an in-memory
/// representation of `book.toml`.
#[derive(Debug, Clone, PartialEq)]
pub struct Config {
    /// Metadata about the book.
    pub book: BookConfig,
    /// Information about the build environment.
    pub build: BuildConfig,
    /// Information about Rust language support.
    pub rust: RustConfig,
    rest: Value,
}
# }
```

qui affiche :

fn main() {
use log::{debug, trace, warn};
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use std::collections::HashMap;
use std::env;
use std::fs::File;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use toml::value::Table;
use toml::{self, Value};

use crate::errors::*;
use crate::utils::{self, toml_ext::TomlExt};

/// The overall configuration object for MDBook, essentially an in-memory
/// representation of `book.toml`.
#[derive(Debug, Clone, PartialEq)]
pub struct Config {
    /// Metadata about the book.
    pub book: BookConfig,
    /// Information about the build environment.
    pub build: BuildConfig,
    /// Information about Rust language support.
    pub rust: RustConfig,
    rest: Value,
}
}

(Il s’agit d’un extrait du fichier config.rs du code source de mdBook).

Fonctions associées aux blocs de code

Comme vous pouvez vous en apercevoir en passant la souris au dessus du bloc de code ci-avant, les blocs de code bénéficient de fonctions particulières, comme la fonction pour copier le contenu du bloc dans le presse-papiers.

Exclusivités Rust

Les codes Rust bénéficient de fonctions supplémentaires pour les tester dans un outil mis à disposition de la communauté :

• le « Run this code » pour compiler le code et le compiler puis (éventuellement) l’exécuter, via un outil de la communauté Rust, directement dans la page : très intéressant pour réaliser des documentations et tutoriels Rust donc ! ;

D’autres fonctions avancées sont possibles moyennant quelques options comme :

• la modification du code par l’internaute directement dans le bloc de code ;
• la numérotation automatique des lignes ainsi que
• le masquage de parties du code ;
• etc.

Position des ```

Note : je vous ai indiqué de disposer les ``` au dessus et en dessous du contenu car nous cherchons à afficher un bloc de code.

Il est possible d’utiliser les ``` dans la même ligne pour affiche un code dans un paragraphe (et non un bloc de code).

Par exemple :

J'ai envie d'écrire ```Ceci est un code``` et je le fais.

affiche :

J’ai envie d’écrire Ceci est un code et je le fais.

Nombre de `

Comme nous avons vu qu’il est possible de doubler le ` dans le cas de l’insertion d’un code dans un paragraphe, nous pouvons en ajouter un quatrième pour encadrer un bloc de code dans lequel nous souhaitons afficher ```.

Par exemple :

````
```
Ceci est un code
```
````

Affiche :

```
Ceci est un code
```

Ou encore :

J'ai envie d'écrire ```` ``` ````.

affiche :

J’ai envie d’écrire ```.

Alternative Markdown : la tabulation

Nous pouvons utiliser une tabulation pour indiquer qu’un texte est un bloc de code.

Par exemple

	Ceci est un code

affiche :

Ceci est un code

Je recommande d’utiliser la notation explicite avec les ``` avant et après le texte car c’est la méthode décrite dans la documentation mdBook officielle et que c’est la méthode la plus lisible, sûre, et extensible.

mdBook : liens internes : Chemins relatifs

Nous devons utiliser des liens internes avec des chemins relatifs pour écrire des liens vers des ressources du projet mdBook en cours.

L’utilisation de liens internes facilite la portabilité du projet : changement de nom de domaine ou de l’emplacement du projet en ligne.

Nous pouvons écrire un lien interne vers :

• un fichier image ;
• un fichiers.md en tant que liens web ouvrant la page correspondante ;
• un chapitre de page mdBook en tant que lien Web ouvrant la page correspondante en affichant et surlignant le chapitre de page ;
• un fichier.md à insérer ;
• un fichier-de-code à insérer, qui peut être un fichiers.rs (écrit en langage Rust).

Les liens des chapitres du sommaire mdBook utilisent les mêmes règles que les liens internes des pages mdBook.

Syntaxe des liens internes

Pour écrire un lien vers un contenu du même projet mdBook, nous utilisons un lien interne qui s’écrit comme suit.

Choix des liens Web pour illustrer

Je prends ici l’exemple de l’écriture d’un lien Web ([texte](lien-interne)).

Les principes décrits ici pour l’écriture d’un lien interne pour un lien Web s’appliquent dans les autres cas d’écriture de liens.

Tous les liens web que nous voyons ci-après sous écrits sous la forme : [Texte](lien) qui s’affiche : Texte` et qui crée un lien Web vers le contenu souhaité.

Lien Web vers une autre page mdBook dans le même dossier

Pour écrire un lien interne vers un fichier.md dans le même dossier, nous écrivons : [Texte](fichier.md).

Lien Web vers un fichier.md dans un sous-dossier

Dans le cas où le fichier.md destination est dans un sous-dossier dossier, nous écrivons [Texte](dossier/fichier.md).

Lien depuis un fichier dans un sous-dossier

Nous avons cette structure de dossiers et fichiers :

|
-----> src (dossier)
       fichier.md
       |--------> dossier-1 (dossier)
                  fichier-du-dossier-1.md
       |--------> dossier-2 (dossier)
                  fichier-du-dossier-2.md
       

Nous écrivons un lien interne vers fichier.md dans fichier-du-dossier-1.md sous cette forme : [Texte](../fichier.md).

Pour écrire un lien vers fichier-du-dossier-2.md dans fichier-du-dossier-1.md, nous écrivons [Texte du lien](../dossier-2/fichier-du-dossier-2.md).

Avec ou sans le ./

Lorsque nous écrivons un lien interne vers un fichier, nous pouvons utiliser le format avec un ./ du dossier en cours, sous la forme [Texte](./dossier/fichier.md) mais ce n’est pas la forme proposée par la documentation officielle mdBook.

Lien vers le site Web mdBook en cours

Si nous éditons un fichier.md dans le dossier source, le lien interne vers le site Web mdBook en cours d’édition est [Texte](./).

Lien depuis un sous-dossier

Si nous avons cette structure de dossiers et de fichiers :

|
-----> src (dossier)
       |--------> dossier (dossier)
                  fichier.md

Le lien vers le site Web mdBook depuis fichier.md est [Texte](../).

Lien Web vers un chapitre de page mdBook

Voir : mdBook : Liens internes : Chapitres de pages mdBook.

Le lien (./) ne fonctionne pas en accès direct aux fichiers

En principe, nous n’accédons pas à notre site en cours de création par accès direct aux fichiers, nous utilisons mdbook serve dont je parle dans mdbook serve : Visualiser nos modifications en continu.

Si nous consultons le site Web mdBook que nous sommes en train d’éditer par accès direct aux fichiers sur notre machine, les liens internes de type (./) nous renvoient vers l’affichage du dossier local nom-du-projet/book (par défaut), par exemple dans mon cas pour ce projet :

Utilisation de liens Web de sous la forme <https://>

Il est possible d’utiliser cette syntaxe pour afficher un lien vers une page mdBook d’un même projet mdBook :

• <https://site-du-projet-mdBook/dossier/fichier.html> pour afficher un lien vers une page mdBook ;
• <https://site-du-projet-mdBook/dossier/fichier.html#chapitre-de-page-mdbook> pour afficher un lien vers un chapitre de page mdBook.

Nous réservons cette syntaxe à des cas particuliers comme cette astuce : mdBook : Surligner toutes les occurrences d’un mot dans une page mdBook.

Nous pouvons choisir d’utiliser cette syntaxe pour rendre l’adresse URL explicite sur le site sans avoir besoin d’écrire [https://site-du-projet-mdBook/dossier/fichier.html](https://site-du-projet-mdBook/dossier/fichier.html) mais cela ne me semble pas pertinent du tout.

mdBook : Liens internes : Chapitres de pages mdBook

Vous avez peut-être déjà remarqué que l’apparence du curseur de notre souris change lorsque nous le faisons passer au-dessus d’un titre de chapitre de page mdBook.

Cela signifie qu’il existe un lien Web qui pointe directement vers ce chapitre de page mdBook.

Le lien Web qui pointe vers un chapitre de page mdBook est de la forme :

https://site-Web-mdBook/dossier/fichier.html#titre-du-chapitre-de-page-mdbook

Syntaxe des liens vers des chapitres de page mdBook

Toutes les lettres sont écrites en minuscules.

Les lettres accentuées sont maintenues comme par exemple é et ç.

mdBook ajoute des - à la place des espaces.

Les codes Markdown de mise en forme ainsi que certains caractères sont supprimés.

Comment utiliser les liens vers des chapitres de page mdBook

Nous utilisons :

• les liens relatifs pour générer des liens web internes au projet mdBook dans nos pages mdBook ;
• les liens absolus pour écrire les liens web vers d’autres sites Web mdBook.

Liens internes, Liens relatifs

La syntaxe du lien relatif d’un chapitre de page mdBook est la suivante.

Lien interne vers un chapitre de page mdBook de la même page mdBook

[Texte du lien](#titre-du-chapitre-de-page-mdbook)

Lien interne vers un chapitre de page mdBook d’une autre page mdBook

[Texte du lien](chemin/fichier.md#titre-du-chapitre-de-page-mdbook)

Mise en avant du chapitre de page mdBook

Lorsque nous suivons un lien vers un chapitre de page mdBook, mdBook ajoute le symbôle » devant le titre du chapitre de page mdBook correspondant, comme sur l’image ci-dessous :

mdBook : Liens externes : Chemins absolus

Liens vers des pages mdBook

Pour insérer des liens web vers une page mdBook d’un autre projet mdBook, nous utilisons un chemin absolu.

Nous avons alors le choix entre deux syntaxes : []() et <https://>.

Lien externe avec la syntaxe []()

Cette syntaxe est celle que nous utilisons pour écrire des liens internes.

Nous écrivons :

[Texte du lien](https://adressedusite.tld/dossier/fichier.html)

qui affiche :

Texte du lien

Lien externe avec la syntaxe <https://>

Nous écrivons le lien sous la forme :

Texte : <https://adressedusite.tld/dossier/fichier.html>

Le lien s’affiche alors ainsi :

Texte : https://adressedusite.tld/dossier/fichier.html

Liens vers des chapitres de pages mdBook

Pour insérer un lien Web vers un chapitre de page mdBook d’un autre projet mdBook, nous ajoutons #titre-du-chapitre-de-page-mdBook à la fin du lien.

Lien externe avec la syntaxe []()

[Texte du lien](https://adressedusite.tld/dossier/fichier.html#titre-du-chapitre-de-page-mdBook)

Lien externe avec la syntaxe <https://>

Texte : <https://adressedusite.tld/dossier/fichier.html#titre-du-chapitre-de-page-mdBook>

Mise en avant du chapitre de page mdBook

Lorsque nous suivons un lien vers un chapitre de page mdBook, le site Web mdBook ajoute le symbôle » devant le titre du chapitre de page mdBook correspondant, comme sur l’image ci-dessous :

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.

mdBook : Markdown : Images

Pour insérer une image dans une page mdBook, il faut écrire un lien interne en ajoutant un point d’exclamation ! accolé au crochet ouvrant.

Par exemple :

![Texte](https://apprendre-et-maitriser-mdbook.marcjestin.fr/images/bloc-notes-mdbook-markdown-code-ceci-est-une-citation.png)

affiche :

Stockage des images

Dans l’exemple précédent, j’ai choisi d’utiliser une image comme si elle était en dehors du projet.

J’ai donc utilisé un lien externe avec un chemin absolu sous un format https://.

Pour intégrer une image dans notre projet mdBook, nous suivons les étapes suivantes :

1. Stocker l’image quelque part dans le dossier source du projet mdBook (nom-du-projet/src par défaut)
   • soit directement dans le dossier source
   • soit dans un sous-dossier, par exemple nom-du-projet/src/images.
     • si nécessaire, nous créons ce dossier.
2. Écrire le code Markdown avec une syntaxe de lien interne avec un chemin relatif.

Lorsque le projet est compilé, soit avec mbook build, soit au travers de mdbook serve, les pages mdBook sont générées et les fichiers des images sont copiées dans le dossier destination (nom-du-projet/book par défaut).
Si nous avons créé un dossier nom-du-projet/src/images pour y placer nos images, nous avons un dossier nom-du-projet/book/images qui contient une copie de ces images et qui est copié sur le serveur Web avec le reste du site Web mdBook lorsque nous copions le contenu du dossier destination comme il se doit.

Exemple de lien avec la même image, cette fois-ci stockée dans mon dossier /src/images.

Voici le code Markdown :

![Texte](images/bloc-notes-mdbook-markdown-code-ceci-est-une-citation.png)

Et voici le rendu :

Bonne pratique

Je recommande d’utiliser la méthode compilateur avec des liens internes sous forme de chemins relatifs en plaçant nos images dans le dossier source du projet mdBook pour améliorer la portabilité.

Il peut arriver que nous adoptions une stratégie différente pour de nombreuses raisons.

mdBook : insérer un code Rust modifiable et exécutable

LA raison principale pour laquelle la communauté Rust s’est dotée de mdBook, c’est la capacité à gérer ce que comporte ce chapitre.

Nous avons vu comme insérer un contenu de fichier .md dans un autre fichier .md avec la consigne {{#include}}.

Il est également possible d’insérer le contenu d’un fichier de code source Rust (dont le nom se termine généralement par .rs) dans un fichier .md avec cette même consigne, sous réserve d’insérer la consigne dans un bloc code Rust.

Ainsi,

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

affiche le bloc de code :

fn main () {
	println!("Hello world!");
}

qui est le contenu du fichier « codes-rust/helloworld.rs » que nous avons préalablement créé.

Traitement par défaut

Si nous ne faisons rien de particulier, le bloc de code Rust propose une option Run this code (exécuter ce code) avec un bouton associé.

En effet, le script fait un lien avec le « Playground » (« espace de jeu » ou « terrain de jeu ») de Rust qui permet de tester des codes Rust et qui :

• les compile ;
• les exécute si la compilation réussit.

Le playground Rust complet est accessible en mode Web à cette adresse : https://play.rust-lang.org/.

Rendre le code Rust modifiable

Nous pouvons donner la possibilité aux lecteurs de modifier le code directement dans notre livre web et de l’exécuter.

Il nous faut tout d’abord indiquer cela dans le fichier de paramètres du compilateur, /nom-du-projet/book.toml, en ajoutant la ligne playground.editable = true dans la section [output.html] :

[output.html]
playground.editable = true

Ensuite, nous indiquons l’option sur chaque bloc de code pour lequel nous souhaitons activer la fonctionnalité avec le mot clef editable (= modifiable, ou éditable) :

```rust,editable
{{#include ./codes-rust/helloworld.rs}}
```

Ce qui produit :

fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}

Le lecteur peut intervenir dans le code du bloc de code ci-avant et dispose maintenant d’un bouton Undo changes (= annuler les modifications) supplémentaire pour revenir à la version proposée au départ par la page mdBook.

Annihiler la possibilité d’exécuter le code

À l’inverse, nous pouvons limiter le bloc de code Rust pour ne proposer que l’affichage et la copie du code.

```rust,ignore
{{#include ./codes-rust/helloworld.rs}}
```

affiche :

fn main () {
	println!("Hello world!");
}

Le bouton Run this code n’est alors plus affiché.

Les dossiers et fichiers de codes Rust sont conservés dans le projet Web

Si nous créons des fichiers de codes Rust, le compilateur les copie dans le dossier book/.

Si nous avons pris soin de créer un dossier spécifique comme je l’ai fait ici (codes-rust/), le dossier existe dans le projet cible et les fichiers sources y sont disponibles.

Par exemple ici : dossier des fichiers de code Rust (dont l’accès vous est interdit par mon serveur nginx, mais je pourrais ouvrir l’accès au parcours de ce dossier si c’était utile).

Nous pouvons également proposer des liens vers un fichier particulier par exemple : fichier de code Rust (ce coup-ci, votre navigateur devrait télécharger le fichier si vous cliquez sur le lien).

Écrire les sources directement dans le fichier .md

Bien entendu, cela fonctionne sans insérer un fichier, et nous pouvons utiliser ces mêmes options pour un code Rust que nous saisissons directement dans le fichier .md.

La rigueur d’un développeur veut que l’on écrive généralement les fichiers .rs à part et qu’on les insère dans le projet comme lorsque nous réalisons des programmes.

Nous pouvons toutefois tout à fait écrire directement dans un fichier .md :

```rust,editable
fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}
```

qui produira :

fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}

Ceci n’est qu’un aperçu

Ceci n’est qu’un aperçu des options offertes par le langage mdBook pour tester et afficher des codes Rust.

mdBook : Numérotation automatique des codes Rust

Paramétrage mdBook

Pour permettre l’affichage des numérotations automatiques des lignes des blocs de code, nous devons ajouter la ligne :

line-numbers=true

dans l’espace

[output.html.playground]

dans le fichier book.toml.

Ce qui donne par exemple :

[output.html.playground]
editable = true
line-numbers=true

Nota bene : la ligne editable = true est également nécessaire.

[output.html.playground]
line-numbers = true

book.title = "Apprendre et maîtriser mdBook"
book.authors = ["Marc JESTIN"]
book.language = "fr"
output.html.additional-css = ["custom.css"]
output.html.sidebar-header-nav = false
output.html.mathjax-support = true
output.html.playground.line-numbers = true
output.html.playground. editable = true
rust.edition = "2024"

Activation de la numérotation automatique dans un bloc de codes

```rust,editable,numbered
(...)
```

Pour que la numérotation puisse se faire, le code doit être marqué editable.

```rust,editable
use std::any::type_name;

fn type_of<T>(_: T) -> &'static str {
	type_name::<T>()
}

fn main() {
	let x = 11;
	let y = 11.;
	let z = "Merci";
    
	println!("Type de x définie par let x = 11 : {}", type_of(x));
	println!("Type de y définie par let y = 11. : {}", type_of(y));
	println!("Type de z définie par let z = \"Merci\" : {}", type_of(z));
}
```

produit par exemple :

use std::any::type_name;

fn type_of<T>(_: T) -> &'static str {
	type_name::<T>()
}

fn main() {
	let x = 11;
	let y = 11.;
	let z = "Merci";
    
	println!("Type de x définie par let x = 11 : {}", type_of(x));
	println!("Type de y définie par let y = 11. : {}", type_of(y));
	println!("Type de z définie par let z = \"Merci\" : {}", type_of(z));
}

Masquage de parties du code

Grâce à cette colonne de numérotation des lignes du code Rust dans le bloc de code, nous disposons de la fonction de masquage de certains blocs dans le code Rust affiché comme dans un EDI.

Par exemple ici, nous pouvons masquer ou afficher les parties de code entre accolades des fonctions en cliquant sur les petits triangles.

mdBook : Cacher des parties du code Rust

Il est possible de cacher des parties de code en insérant un croisillon suivi d’une espace # au début des lignes que l’on souhaite cacher.

Par exemple :

```rust
# use std::any::type_name;
#
fn type_of<T>(_: T) -> &'static str {
	type_name::<T>()
}

fn main() {
# 	let x = 11;
# 	let y = 11.;
# 	let z = "Merci";
#    
	println!("Type de x définie par let x = {x:?} : {}", type_of(x));
	println!("Type de y définie par let y = {y:?} : {}", type_of(y));
	println!("Type de z définie par let z = {z:?} : {}", type_of(z));
}
```

affiche :

use std::any::type_name;

fn type_of<T>(_: T) -> &'static str {
	type_name::<T>()
}

fn main() {
	let x = 11;
	let y = 11.;
	let z = "Merci";
   
	println!("Type de x définie par let x = {x:?} : {}", type_of(x));
	println!("Type de y définie par let y = {y:?} : {}", type_of(y));
	println!("Type de z définie par let z = {z:?} : {}", type_of(z));
}

Le·la lecteur·trice peut afficher / masquer les lignes concernées en cliquant sur l’œil qui est proposé automatiquement lorsque la fonction est utilisable.

L’intérêt de la manœuvre est de masquer une partie du code pour rendre l’affichage plus lisible tout en laissant ce code à disposition :

• pour le lecteur·trice intéressé·e à en savoir plus ;
• pour le compilateur qui peut ainsi faire tourner le code complet, code qui ne serait plus valide si nous supprimions réellement ces lignes plutôt que de simplement les masquer.

Nota : Malheureusement, cette fonction n’est pas accessible dans des blocs de code marqués comme editable.

mdBook : Markdown : notes de bas de page

Pour insérer des notes de bas de page, il faut procéder comme suit :

1. insérer le texte [^label] à l’endroit ou l’index doit figurer ;
2. insérer le texte [^label]: et
3. écrire le contenu de la note de bas de page à la suite.

mdBook numérote automatiquement les notes de bas de page lorsqu’il génère les fichiers du document.

mdBook place automatiquement les notes de bas de page en bas de la page créée.

Par exemple :

Ceci est un exemple n°1 d'insertion de note de bas de page [^note1].

[^note1]: Ceci est la note n°1 associée.

Ceci est un exemple n°2 d'insertion de note de bas de page [^note2].

[^note2]: Ceci est la note n°2 associée.

>« Ceci est un exemple avec deux notes dans la même ligne : la n°3 [^note3] et la n° 4 [^note4]. »

[^note3]: Ceci est la note n°3 associée.

[^note4]: Ceci est la note n°4 associée.

s’affiche comme vous pouvez le voir :

Ceci est un exemple n°1 d’insertion de note de bas de page ¹.

Ceci est un exemple n°2 d’insertion de note de bas de page ².

« Ceci est un exemple avec deux notes dans la même ligne : la n°3 ³ et la n° 4 ⁴. »

Des labels explicites (pour nous)

La présentation qui est faite ci-avant est très « naïve ».

Il est préférable d’utiliser des labels (uniques) explicites pour nous en fonction du contexte.

Le code Markdown

> L'impact de l'intelligence artificielle sur le marché du travail reste un sujet de débat intense parmi les économistes. [^note-emploi] Alors que certains prédisent une automatisation massive, d'autres anticipent plutôt une augmentation des capacités humaines grâce à ces technologies. [^note-productivite]

[^note-emploi]: **Étude du MIT (2024) :** L'étude montre que la transition professionnelle sera progressive mais nécessitera une requalification massive de la main-d'œuvre.

[^note-productivite]: **Rapport McKinsey :** Les entreprises adoptant l'IA observent en moyenne une hausse de 15 % de leur efficacité opérationnelle.

Le rendu

L’impact de l’intelligence artificielle sur le marché du travail reste un sujet de débat intense parmi les économistes. ⁵ Alors que certains prédisent une automatisation massive, d’autres anticipent plutôt une augmentation des capacités humaines grâce à ces technologies. ⁶

1. Ceci est la note n°1 associée. ↩

2. Ceci est la note n°2 associée. ↩

3. Ceci est la note n°3 associée. ↩

4. Ceci est la note n°4 associée. ↩

5. Étude du MIT (2024) : L’étude montre que la transition professionnelle sera progressive mais nécessitera une requalification massive de la main-d’œuvre. ↩

6. Rapport McKinsey : Les entreprises adoptant l’IA observent en moyenne une hausse de 15 % de leur efficacité opérationnelle. ↩

mdbook serve : Utilisation avancée

Travailler sur plusieurs projets mdBook simultanément

Si nous travaillons sur plusieurs projets simultanément, nous pouvons leur attribuer des numéros de port différents avec l’option -p numdeport.

Nous pouvons par exemple valider cette commande en nous plaçant dans le dossier du projet mdBook 1 :

mdbook serve -o -p 7777

et, une fois dans le dossier du projet mdBook 2, valider la commande :

mdbook serve -o -p 7778

Nous accédons alors aux sites Web mdBook correspondants en local avec les deux adresses :

http://localhost:7777
http://localhost:7778

Optimisation avec un petit script shell

Voici un exemple de script shell que nous pouvons ajouter dans notre dossier ~/bin.

Le script démarre les services mdbook serve et ouvre une fenêtre de notre navigateur web sur chacun des deux sites Web mdBook.

Nous en profitons pour lui faire ouvrir notre gestionnaire de fichiers (ici nautilus de GNOME) directement dans des deux dossiers sources où nous devons intervenir.

cd ~/mdbooks/projet-mdBook-1/
mdbook serve -o -p 7777 &
cd ~/mdbooks/projet-mdBook-2/
mdbook serve -o -p 7778 &

nautilus ~/mdbooks/projet-mdBook-1/src &
nautilus ~/mdbooks/projet-mdBook-2/src &

Rassembler les fenêtres du navigateur web

Si notre navigateur web par défaut est Mozilla Firefox, nous pouvons utiliser l’extension Merge Windows : https://addons.mozilla.org/fr/firefox/addon/merge-window.

Pour nous en servir, nous cliquons sur le bouton droit dans une fenêtre de Mozilla Firefox puis sur le menu contextuel Merge all windows.

Toutes les fenêtres Mozilla Firefox ouvertes sont alors rassemblées sous forme d’onglets dans la même fenêtre.

Fermeture des services

Sous Linux, lorsque nous avons terminé de travailler sur nos projets mdBook, un simple killall mdbook ferme toutes les instances mdbook serve en cours d’exécution.

Si tant est que nous en ayons besoin (mdbook serve consomme peu de ressources systèmes).

Transférer les contenus avec un script shell

De même, nous pouvons écrire un script shell pour charger les nouvelles versions sur notre serveur Web.

mdBook : renommage d’une page mdBook

Si nous utilisons mdbook serve, voir le chapitre de page mdBook Consignes pour mdbook serve (dans cette même page) AVANT de lire ce qui suit.

Je recommande de faire une sauvegarde du dossier source avant de commencer une opération de ce type au moins les premières fois avant d’être sûr·e de bien maîtriser le sujet.

De même, je recommande de désactiver mdbook serve le temps d’avoir fait le tour de la question jusqu’à bien maîtriser le processus lorsque nous souhaitons effectuer des opérations de refactorisation (refactoring) de nos codes sources de projet mdBook.

Consignes sans mdbook serve

Si nous nous apercevons que nous souhaitons changer le titre d’une page mdBook, il nous faut :

• changer le nom du fichier.md ;
• Dans le fichier SUMMARY.md :
  • Changer le titre entre [] (si nécessaire pour qu’il corresponde au nouveau nom du fichier.md) ;
  • Changer le nom du fichier.md dans le lien entre () pour qu’il corresponde bien au nouveau nom de fichier.md.
• ouvrir le fichier.md sous son nouveau nom pour changer le titre précédé d’un # du début afin de le faire correspondre au (nouveau) titre figurant dans le sommaire mdBook.
• rechercher les éventuels liens vers fichier.md dans les autres fichiers du projet mdBook pour les mettre à jour avec le nouveau nom du fichier.md.
• enregistrer tous les fichiers ainsi modifiés.
• faire un mdbook build pour
• vérifier que tout se passe bien :
  • ouvrir le sommaire mdBook du site Web mdBook et vérifier son contenu affiché ;
  • cliquer sur le lien de la page mdBook pour nous assurer qu’il nous mène bien à la page souhaitée ;
  • contrôler la liste des fichiers dans le dossier source : il peut arriver que le compilateur mdBook recrée un fichier avec l’ancien nom de fichier.md;
  • Si un fichier portant l’ancien nom de fichier.md réapparaît, c’est qu’il existe un lien vers celui-ci quelque-part dans notre projet mdBook.
    Il nous faut alors
    • trouver ce lien,
    • corriger le lien,
    • supprimer le fichier.md avec l’ancien nom que le compilateur mdBook a créé,
    • relancer un mdbook build puis reprendre à l’étape contrôler la liste des fichiers dans le dossier source.
  • faire une recherche pour nous assurer qu’aucun lien vers l’ancien nom de fichier.md n’existe dans le projet mdBook.

Cette procédure vaut pour un déplacement de fichier même sans modification du nom de fichier ni du titre associé.

Un seul à la fois

Je recommande de ne changer qu’un seul nom de page mdBook à la fois et de prendre le temps de bien vérifier avant de procéder à d’autres changements de noms de pages mdBook.

Consignes pour mdbook serve

Si mdbook serve est en fonctionnement, comme celui-ci vérifie la liste des fichiers.md en boucle en permanence :

• si nous enregistrons SUMMARY.md dans sa nouvelle version sans avoir renommé le fichier.md, mdbook serve crée le nouveau fichier, à côté de l’ancien que nous n’avons pas encore renommé ;
• si nous commençons par renommer le fichier.md, mdbook serve recrée le fichier sous l’ancien nom à côté du fichier que nous venons de renommer.

En principe, la procédure proposée dans Consignes sans mdbook serve, si elle est réalisée dans l’ordre proposé, fonctionne sans avoir besoin d’interrompre mdbook serve.

Toutefois, je recommande de désactiver mdbook serve le temps d’avoir fait le tour de la question jusqu’à bien maîtriser le processus.

Caractères autorisés

Pour connaître les caractères autorisés pour le nommage des sous-dossiers et des fichiers.md, voir mdBook : Caractères autorisés.

mdBook : MathJax pour les formules mathématiques

À propos de MathJax

Voir la page du MédiaWiki : https://happynumeric.fr/mediawiki/index.php/MathJax.

Activation de MathJax

Pour pouvoir utiliser MathJax dans mdBook, nous devons commencer par ajouter :

[output.html]
mathjax-support = true

dans le fichier book.toml de notre projet mdBook.

Utilisation de MathJax

En cours…

mdBook : surligner toutes les occurences d’un mot dans une page mdBook

Il suffit d’observer le fonctionnement du moteur de recherche proposé avec mdBook pour comprendre comment celui-ci indique au moteur de surligner les occurences d’un mot.

En effet, l’affichage d’une page mdBook avec recherche surligne toutes les occurences du mot recherché.

Par exemple, après avoir cherché « surligner » dans ce bloc-notes, et cliqué sur cette page, nous avons un lien URL :

https://happynumeric.fr/Bloc-notes-mdBook/mdbook-surligner-toutes-les-occurences-d-un-mot-dans-une-page.html?highlight=surligner#mdbook--surligner-toutes-les-occurences-dun-mot-dans-une-page

dans lequel nous identifions rapidement la partie qui nous intéresse : ?highlight=surligner juste après .html.

Essayons maintenant de faire la même chose avec un autre mot et une autre page de ce site Web mdBook, par exemple :

https://happynumeric.fr/Bloc-notes-mdBook/mdbook-markdown-mise-en-forme-des-caractères.html?highlight=mot

Miracle de la technologie, toutes les occurences du mot « mot » sont surlignées, comme lors d’une recherche.

Uniquement avec des liens HTML

La syntaxe

[mot surligné ou pas ?](./mdbook-markdown-mise-en-forme-des-caractères.md?highlight=mot)

ne génère pas un lien qui permet de surligner le mot dans la page. Le ?highlight=mot est visiblement ignoré par le compilateur mdBook.

Pour tester : mot surligné ou pas ?

Cela ne fonctionne qu’avec des liens exprimés en chemin absolu et en HTML.

Voilà en tout cas une petite astuce qui pourrait servir à certains.

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.

mdBook : particularités de la syntaxe

Sous-chapitres : limitation à 6 niveaux

Lorsque nous essayons :

## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6
####### Titre de niveau 7
######## Titre de niveau 8

les niveaux 7 et 8 ne sont pas interprétés par le compilateur comme nous pouvons le voir :

Titre de niveau 2

Titre de niveau 3

Titre de niveau 4

Titre de niveau 5

Titre de niveau 6

####### Titre de niveau 7 ######## Titre de niveau 8

Nous ne disposons donc que de 6 niveaux dans nos pages chapitres (5 en réalité, le niveau 1 étant réservé aux titres de chapitres et ne devant apparaître en principe qu’une fois tout en haut d’une page).

Ceci est conforme à la spécification HTML.

Choix du caractère Markdown pour les listes non numérotées

Le - suivi d’une espace en début de ligne est interprété de la même manière que le *.

Je recommande de n’utiliser que le « * » qui est le caractère indiqué dans la documentation officielle mdBook (lists).

Voici par exemple un code Markdown :

* liste de niveau 1
   - liste de niveau 2
     * liste de niveau 3
     * liste de niveau 3
       - liste de niveau 4

qui affiche :

• liste de niveau 1
  • liste de niveau 2
    • liste de niveau 3
    • liste de niveau 3
      • liste de niveau 4

mdBook : indentation : espaces ou tabulations ?

Je recommande d’utiliser des tabulations pour l’indentation et non des espaces, dans mdBook comme ailleurs.

Si toutefois vous utilisez des espaces, voici quelques éléments à prendre en considération pour les listes.

Nota bene : Lorsque vous aurez terminé de lire cette page mdBook, si vous avez tout bien compris, vous utiliserez les tabulations.

Indentation avec des espaces dans les listes

Il faut mettre au moins autant d’espaces que le nombre de caractères à gauche du texte du niveau précédent, espace compris :

• 2 caractères pour « * » (étoile + espace) ;
• 3 caractères pour « 1. » (un + point + espace).

Dans le cas où vous ne respectez pas ce nombre minimum, le compilateur mdBook interprète mal les niveaux.

Par exemple :

* liste de niveau 1
  * liste de niveau 2
 * liste de niveau 2 mal positionnée
    * liste de niveau 3 mal comprise car l'élément précédent est mal positionné.

produit :

• liste de niveau 1
  • liste de niveau 2
• liste de niveau 2 mal positionnée
  • liste de niveau 3 mal interprétée par le compilateur car l’élément précédent est mal positionné.

Bref, c’est bien plus sûr, plus rapide, plus simple et moins coûteux en octets avec des tabulations !

Fin de la blague.

mdBook : Caractères autorisés pour les noms de dossiers et de fichiers

Les noms de dossiers et de fichiers peuvent être écrits

• en lettres minuscules et capitales (TEST.md est accepté par exemple) ;
• avec des caractères accentués ou autres : le ç est accepté, le œ également, etc.
  • les lettres capitales accentuées (É) ou spéciales (Ç) sont bien prises en charge.

Le nom

TeSTçœÉçÇ&$€.md

est parfaitement accepté et respecté par exemple.

Certains disent que les caractères accentués avec capitales améliorent le référencement naturel dans les moteurs de recherche web et la lisibilité pour les lecteurs francophones.

Je recommande de rester sur des caractères ASCII (lettres capitales incluses).

Cas d’une espace : pas de remplacement automatique

Les caractères espace ne sont pas acceptés ni remplacés automatiquement par un - ou un _ par mdBook.

Je recommande de les éviter (même si cela fonctionne) et d’utiliser des - et / ou des _.

Attention : Lorsqu’un nom n’est pas correct, le compilateur mdBook ne crée pas le dossier et / ou le fichier ni ne signale aucune erreur ni n’émet aucun avertissement.

mdBook : Dictionnaire anglais français

Dans la mesure où on ne trouve, en dehors de ce livre, que des documentations en anglais, je vous propose ce « dictionnaire » pour vous aider, si nécessaire, à faire le lien entre les expressions que j’ai choisi d’utiliser et la documentation officielle de mdBook.

français -> anglais

Sommaire mdBook

anglais -> français

Sommaire mdBook

mdBook : Questions sans réponses

Liste des questions en attente de réponses

mdBook : comment insérer une image dans la table des matières SUMMARY.md ? https://happynumeric.fr/phpbb/viewtopic.php?t=98

mdBook : comment bénéficier d’un correcteur orthographique et grammatical lors de l’édition de nos contenus ? https://happynumeric.fr/phpbb/viewtopic.php?t=100

mdBook : n’incrémente pas les numéros des notes de bas de page : https://happynumeric.fr/phpbb/viewtopic.php?t=104

mdBook : ne positionne pas les notes de bas de page en bas de la page : https://happynumeric.fr/phpbb/viewtopic.php?t=105

mdBook : est-il multilangue et si oui, comment les gérons-nous dans un projet hors Git ? https://happynumeric.fr/phpbb/viewtopic.php?t=107

mdBook : Mon bloc de code Rust n’est pas modifiable (editable) alors que j’ai bien mis l’option qu’il faut. https://happynumeric.fr/phpbb/viewtopic.php?t=111

mdBook : comment ajouter une ligne {{ #include }} dans un bloc de code sans qu’elle soit interprétée ? https://happynumeric.fr/phpbb/viewtopic.php?t=112

mdBook : MathJax : guides et modes d’emploi : https://happynumeric.fr/phpbb/viewtopic.php?t=114

mdBook : que faire ? [WARN] (mdbook::renderer::html_handlebars::hbs_renderer): output.html.copy_fonts is deprecated. https://happynumeric.fr/phpbb/viewtopic.php?t=117

mdBook : que signifie le message « [INFO] (mdbook::book): Running the html backend » https://happynumeric.fr/phpbb/viewtopic.php?t=118

mdBook : comment choisir le sous-thème par défaut de notre site Web mdBook ? https://happynumeric.fr/phpbb/viewtopic.php?t=123

Proposer des questions

Pour proposer de nouvelles questions sans réponses, vous pouvez me contacter ou créer le sujet dans les forums dans l’espace dédié à mdBook https://happynumeric.fr/phpbb/viewforum.php?f=122.
Je serai informé de votre votre message dans les forums et je pourrai créer le lien dans cette page.

À bientôt,

Marc JESTIN

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 ?

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.

Exemple.

Nous avons cette structure de fichiers :

|----- src (dossier)
       SUMMARY.md
       page-mdBook.md
       page-mdBook-cible.md
       |----- fichiers-inseres (dossier)
              fichier-insere.md

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

{{ # include ./mon-dossier/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-inséré.md est :

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

Autre exemple :

Nous avons cette structure de fichiers :

|----- src (dossier)
       SUMMARY.md
       page-mdBook.md
       |----- rubrique-1 (dossier)
              page-mdBook-cible.md
       |----- fichiers-inseres (dossier)
              fichier-insere.md

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

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

mdBook : lacunes du compilateur

Astuce : il peut arriver que des captures d’écran soient peu lisibles.
Pour voir les images correctement, cliquez bouton droit puis ouvrez les dans un nouvel onglet.

mdBook : erreur : include : Fichier manquant

Lorsque le préprocesseur de mdBook analyse les fichiers, il peut arriver qu’il trouve une consigne {{ #include }} qui indique une adresse de fichier incorrect.

Dans un tel cas, il indique une erreur comme suit :

Il n’indique pas pour quel fichier source cette erreur est générée.

mdBook : avertissement : include dans un bloc code : Fichier manquant

Si, comme c’est le cas dans ce livre, nous mettons un exemple de {{ #include }}, dans un bloc code, avec une adresse de fichier qui n’existe pas dans notre projet, le pré-processeur indique une erreur suivie d’unn avertissement comme ceci :

En principe, cet {{ #include }} ne devrait pas être interprété ou analysé par le préprocesseur mdBook puisqu’il est à l’intérieur d’un bloc code.

Cela n’est pas trop gênant dans la mesure où cela ne bloque pas la compilation, mais c’est très perturbant.

Ces lacunes identifiées en mars 2023 sont toujours d’actualité en juillet 2026.

mdBook : Atouts et limites

Cette page a été écrite en mars 2023.

mdBook présente des avantages et des inconvénients, des atouts et des limites.

Je vous propose de vous donner mon analyse ici.

Une utilisation fastidieuse

Un éditeur est plus pratique

Le problème de l’approche en mode compilation d’un document, ou d’un site Web est que cela est plus fastidieux et pénible à la longue qu’une simple édition surtout s’il s’agit d’une édition WYSIWYG, en voyant directement le résultat de notre travail comme dans Wordpress ou MédiaWiki par exemple.

Il manque des outils à valeur ajoutée comme la correction orthographique et grammaticale

Par ailleurs, l’absence d’un éditeur riche nous prive de la correction orthographique et grammaticale que nous avons avec des outils de type CMS : comme nous les utilisons dans le navigateur web, nous pouvons nous servir d’extensions pour nous aider à repérer nos fautes dans le texte.

L’absence de continuité et de « mode plan » (dynamique) est très pénalisante

Par exemple, si nous modifions le titre d’un chapitre dans SUMMARY.md, il faut penser à :

• renommer le fichier md correspondant à la fois dans le lien entre parenthèses et dans la structure de dossiers et fichiers ET
• modifier le titre qui s’affiche en haut du fichier .md correspondant.

Il peut exister des versions décalées

Du fait du fonctionnement du système, nous sommes comme dans le cadre d’un programme en développement.

De ce fait, l’auteur ou les auteurs d’un projet mdBook peuvent être en train de travailler sur la prochaine version alors qu’elle n’est pas encore chargée sur le site de production.

C’est assez habituel dans le monde du développement.

Ça l’est moins pour des béotiens qui peuvent être perturbés par cela.

Des fonctionnalités très limitées

mdBook n’offre pas grand chose comme possibilités.

On ne peut pas, par exemple :

• intégrer des vidéos comme on intègre des images ;
• etc.

Quels avantages ?

Mais alors, quels sont les avantages de ce produit ?

Utiliser mdBook, c’est intégrer la logique de la communauté Rust et espérer que l’outil sera enrichi à l’avenir.

Utiliser mdBook, c’est bénéficier de cette logique de site compilé (« buildé ») et a priori donc plus performant et plus sûr.
Propos à nuancer car

• un site Web mdBook comporte des scripts que la plupart des utilisateurs ne vérifieront pas ;
• mdBook s’appuie sur une chaîne d’approvisionnement, qu’il ne respecte pas complètement puisque nous savons que les modifications dans handlebars.

Utiliser mdBook, c’est bénéficier de l’outil de compilation et d’exécution de codes Rust intégré.
Voilà là un avantage bien mince lorsque l’on sait à quel point :

• le Playground Rust est accessible et propose de plus en plus d’outils ;
• il n’est pas difficile de reprendre le code d’intégration pour s’en servir ailleurs.

« Pourquoi c’est faire ? »

Une des questions que je pose toujours est : « Pourquoi les développeurs ont-ils décidé de le produire alors même qu’il existait, au moment où ils ont fait ce choix, de nombreux outils capables de produire de la documentation de qualité ? »

Je n’ai franchement pas la réponse à cette interrogation à ce jour.

En synthèse

mdBook est un outil très limité qui ne peut convenir à ce jour et dans l’état de mes connaissances que pour construire un site en anglais (faute d’une logique de localisation sérieuse et facile d’accès) sous forme de livre et avec une présentation de sommaire « à plat » qui peut vite devenir interminable.

mdBook ne m’offre pas de perspectives importantes pour construire quelque-chose.

À tel point que je suis en train de réfléchir pour plutôt construire mes blocs-notes Rust avec un support type MediaWiki qui, de mon point de vue, est beaucoup plus pratique car il propose :

• une création dynamique et souple de site Web qui permet de générer nativement et sans effort la génération progressive du contenu ;
• des capacités à intégrer toutes sortes de médias audio, vidéo, images.
• une capacité d’extensibilité et de gestion de gros volumes de pages, qui n’a de limite que :
  • la créativité du gestionnaire ;
  • ses capacités de travail ;
  • sa capacité à créer une ou plusieurs approches de présentation et de parcours guidé de son contenu.
• le tout en offrant une immense souplesse quant aux manières d’exploiter l’outil.

Je pense que les développeurs de mdBook ont manqué de vista lorsqu’ils ont créé l’outil et qu’ils auraient pu, et dû, s’appuyer sur quelque-chose de « plus grand » et ne pas perdre de temps à créer cet outil.

Par ailleurs, la documentation est

• par trop orientée développeurs et
• incomplète et insuffisante.

Je vais toutefois continuer de consolider mes savoir-faire sur l’outil et de suivre ses évolutions à l’avenir.

En espérant que les besoins internes de la communauté les conduiront à développer un outil plus puissant, plus performant, plus riche, plus modulaire, et plus facile à paramétrer, localiser et gérer.

Tout un programme !

En juillet 2026, force est de constater que l’outil n’a que très peu évolué.

mdBook : Suggestions d’améliorations et remarques

Suggestions d’amélioration

Créer un outil de création sans ruptures

Il faudrait permettre la création d’un plan de document unique et, ensuite, nous donner la possibilité de choisir le découpage du projet en sous-documents.

Créer un éditeur WYSIWYG

Il est évident que cela serait plus de proposer un environnement de création graphique, visuel, qui permet de voir le rendu lors de la saisie et des opérations.

Cet outil pourrait être associé, tel à un EDI à :

• des touches d’action rapide ;
• une aide contextuelle.

Proposer la gestion de redirections

Si nous sommes amenés à modifier notre plan de chapitres et sous-chapitres ou simplement le nommage de fichiers, il serait intéressant de nous permettre de générer une liste de redirections de liens.

Si cela était envisagé ou fait, il faudrait réfléchir à faire en sorte que cela fonctionne avec les sous-chapitres (#titre-de-sous-chapitre).

Donner plus de liberté dans SUMMARY.md

Les usages proposés dans SUMMARY.md sont très limités, trop à mon avis.

Proposer des outils de génération automatique de certaines informations

Je pense que tout document devrait être associé à des informations clefs.

Dans le temps, on nous apprenait à réaliser des « cartouches » et à y apposer un certain nombre d’informations.

Ici par exemple :

• le nom du ou des auteurs,
• la date de création,
• la date de dernière mise à jour,
• l’outil utilisé pour la création,
• etc.

Ces informations pourraient être reportées :

• au niveau document ;
• au niveau d’une page.

J’ai pris soin, dans la mesure du possible, et à partir du 17 mars 2023, d’intégrer une date de création et une date et heure de dernière mise à jour dans mes pages et dans le sommaire. Il serait très pratique que cela soit proposé automatiquement par le compilateur.

Bien entendu, cela suppose de gérer quelques informations supplémentaires.

Remarques

Choix de Markdown

Il est dommage, je trouve, de s’appuyer sur Markdown : ce langage, comme beaucoup d’autres (BBcode par exemple) est très pauvre et fastidieux à utiliser.

Il manque d’évolutivité.

Par ailleurs, je crois qu’il vaut mieux limiter le nombre de langages de référence sauf, bien entendu, dans le cas où un saut technologique nécessite d’abandonner un précédent langage.

HTML est un langage qui, jusqu’à preuve du contraire, remplit parfaitement son rôle pour ce qui est de créer des supports pour le Web : nous devrions donc, tous ensemble, nous concentrer sur l’apprentissage, la maîtrise, la valorisation et l’amélioration continue de celui-ci.

mdBook : Documentation officielle

La documentation officielle mdBook n’existe pour le moment qu’en anglais.

Voici le lien vers celle-ci :

mdBook Documentation, Le guide officiel de mdBook : https://rust-lang.github.io/mdBook.

À propos

mdBook

Ce site est construit avec mdBook, l’outil de documentation externe de la communauté Rust.

Auteur

Je m’appelle Marc JESTIN.

J’ai 55 ans, je réside actuellement en FRANCE à SURGÈRES (17).

Pour en savoir plus ou pour me contacter, rendez-vous sur

https://marcjestin.fr

Mes sites au sujet de Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook