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


Présentation

Bonjour et bienvenue dans ce bloc-notes mdBook.

J'y partage des informations, des outils et des observations qui m'ont été ou me sont utiles pour

  • apprendre à maîtriser mdBook et
  • travailler avec mdBook.

Avertissements

Ce document est une création personnelle.

C'est un bloc-notes.

Il n'est pas :

  • un guide d'apprentissage pas-à-pas ;
  • une référence exhaustive.

mdBook : sites utiles

Je parle aussi de mdBook dans le MédiaWiki : https://happynumeric.fr/mediawiki/index.php/MdBook.

Je vous invite à venir échanger sur les forums dans l'espace dédié à mdBook https://happynumeric.fr/phpbb/viewforum.php?f=122.

À bientôt,

Marc JESTIN — Happy Numeric

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

Autres sites utiles

Sites mdBook

J'ai créé :

Autres outils de création Web

J'ai mis en ligne d'autres sites pour parler de numérique :

Site happynumeric.fr

https://happynumeric.fr


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

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


À propos de cette page

Création : 14 mars 2023

Dernière mise à jour : 23 mars 2023 19:07


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


Terminologie

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

Les expressions des concepts principaux sont toujours formulées 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 ;
  • la compilation par le compilateur mdBook ;
  • la publication du site Web mdBook ainsi produit dans le dossier destination.

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 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.

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.

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 :

  • « 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.

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

  • « Présentation » ;

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ée 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.

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


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

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


À propos de cette page

Création : 15 mars 2023

Dernière version : 23 mars 2023 23:36


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


Conventions d'écriture

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 :

Conventions d'écriture dans ce Bloc-notes mdBook

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.

Je souligne toutes les expressions définies dans ce bloc-notes mdBook ainsi que les composants clefs d'un projet mdBook en caractères gras.

Cela inclut les noms de certains fichiers clefs comme SUMMARY.md ou book.toml.

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 Mardown, par exemple ` ou *.

J'écris les mots anglais en caractères italiques, et 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 la convention d'écriture relative à la typographie française.

La règle peut être différente dans les conventions de nommage ou des conventions de codage.

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 savons que nous ne disposons par du caractère espace insécable qui est pourtant 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. Je « fais avec » et j'utilise une espace en lieu et place d'une espace insécable.

J'espère qu'un jour, enfin, les développeurs prendront le temps de se pencher sur ce point et proposeront des solutions.

Ces solutions peuvent être :

  • de faire évoluer le langage Markdown ;
  • d'ajouter des fonctions dans les scripts de création des pages au format HTML (l'espace insécable existe en langage HTML, il s'écrit   comme « Non Breakable SPace » (= « espace qu'on ne peut pas casser » litéralement) ;
  • de proposer des interpréteurs pour améliorer le code HTML des pages Web :
    • dans les serveurs Web ;
    • dans dans les navigateurs Web.

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

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


À propos de cette page

Création : 14 mars 2023

Dernière mise à jour : 22 mars 2023 17:24


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


Conventions de nommage

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 :

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 acceptés, par exemple le é ou le ç.
  • pour le dossier du projet mdBook :
    • lettres capitales ou majuscules autorisées ;
    • respect de la majuscule au nom propre Rust ;
    • 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 d'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.

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 complexen mais des suites d'un choix de nommage d'un des dossiers, le comportent 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-estimez pas l'impact de ce qui peut ressembler de loin à des détails tatillons ;
  2. ici l'enjeu est faible, et l'intérêt est grand (référencement naturel et lisibilité). Je ne ferais pas ce choix s'il s'agissait d'un développement de code informatique.

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

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


À propos de cette page

Création : 14 mars 2023

Dernière mise à jour : 21 mars 2023 22:33


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


Conventions de codage

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 l'homogénéité et la lisibilité de nos supports.

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

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 ce Bloc-notes mdBook.

Le langage Markdown disposer 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.


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

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


À propos de cette page

Création : 14 mars 2023

Dernière mise à jour : 21 mars 2023 22:29


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


mdBook : Architecture des fichiers

Un projet mdbook se crée et vit sa vie dans un dossier local (je ne parle que de ce cas d'application dans ce Bloc-notes mdBook).

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

mdbook init

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

Note : mdBook ne tient pas compte du nom de projet que nous lui indiquons en réponse à la seconde question.

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 mdBoolk 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 par exemple dans le cas de ce site Web mdBook :

{mondossierweb}/happynumeric.fr/Bloc-notes-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.


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

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


À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 22 mars 2023 15:32


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


mdBook : 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 :

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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 20 mars 2023 19:25


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


mdBook : 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 Bloc-notes mdBook,

https://happynumeric.fr/Bloc-notes-mdBook

la page mdBook qui s'affiche est :

https://happynumeric.fr/Bloc-notes-mdBook/mdbook-bloc-notes-présentation.html.

qui correspond au premier chapitre du sommaire mdBook : « Présentation ».


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 pour ce Bloc-notes mdBook ;
  • 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.


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

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


À propos de cette page

Création : 18 mars 2023

Dernière mise à jour : 23 mars 2023 19:47


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


mdBook 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 :

https://localhost:3000

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.


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

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


À propos de cette page

Création : 19 mars 2023

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


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


mdBook : SUMMARY.md : structurer les pages mdBook

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

Il comporte les informations du sommaire mdBook.

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

Important

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

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

Organisation et syntaxe

SUMMARY.md a un double rôle :

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

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

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

Rubriques du sommaire mdBook

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

# Titre de rubrique

Exemples ici :

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

Chapitres du sommaire mdBook

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

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

Indentation

L'indentation permet de signaler des sous-chapitres.

Par exemple :

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

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

Chapitres du sommaire mdBook numérotés

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

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

Chapitres du sommaire mdBook non numérotés

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

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

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

Numérotation des chapitres du sommaire mdBook

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

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

Avec ou sans lien

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

Par exemple :

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

Cas d'application :

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

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

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

Liens vers les pages mdBook

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

Ces liens peuvent être relatifs ou absolus.

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

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

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

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

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

Nous procédons ainsi :

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

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

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

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

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

De l'importance de structurer notre projet mdBook

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

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

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

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

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

Particularités de SUMMARY.md

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

Voir mdBook : SUMMARY.md : Spécificités.


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

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


À propos de cette page

Création : 15 mars 2023

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


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


mdBook : 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.

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 Bloc-notes mdBook.

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 Bloc-notes mdBook et… Restons vigilants !


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

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


À propos de cette page

Création : 18 mars 2023

Dernière mise à jour : 23 mars 2023 21:02.


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


mdBook : 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 actuellement vers la « GitHub Flavored Markdown Spec » (spécification MarkDown saveur Github) 1.

À 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 bloc-notes mdBook 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.


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

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


À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 23 mars 2023 21:16


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


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


mdBook : 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 je le fais dans cette page mdBook 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 Bloc-notes mdBook.


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

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


À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 23 mars 2023 21:27


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


mdBook : 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 en fonction de la ligne qui la précède dans SUMMARY.md

Comme nous pouvons le voir ici :

Ligne horizontale après indentation du sommaire

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

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

Ligne horizontale après indentation du sommaire

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.


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

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


À propos de cette page

Création : 18 mars 2023

Dernière mise à jour : 23 mars 2023 21:30


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


mdBook : 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) # 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

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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 23 mars 2023 21:46


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


mdBook : 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.

Note : Le - fonctionne également en langage Markdown mais il n'est pas recommandé de l'utiliser.

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.

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.


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

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


À propose de cette page

Création : 17 mars 2023

Dernière mise à jour : 20 mars 2023 21:39


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


mdBook : 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 :

Colonne 1Colonne 2Colonne 3
Contenu 1Contenu 2Contenu long 3
Contenu 1Court 2Contenu 3
Contenu 1Contenu 2Contenu 3

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 :

Colonne 1Colonne 3
Contenu 1l1Contenu long 3 mais pas trop long
Contenu 1l2Contenu 3
Contenu vraiment très très très long et d'ailleurs on se demande jusqu'où il va aller 1l3Contenu 3

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 :

Mon tableau
Ceci est une ligne
Ceci est une nouvelle ligne

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 :

Colonne 1Colonne 2Colonne 3
Contenu 1Contenu 2
Contenu 1
Contenu 1Contenu 2Contenu 3

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 :

Colonne 1Colonne 2Colonne 3
Contenu 1Contenu 2
Contenu 1
Contenu 1Contenu 2Contenu 3

Je recommande d'écrire les tableaux « strictement » 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 |).
Le tableau s'affiche alors sous cette forme :

Contenu 1l1Contenu long 3 mais pas trop long
Contenu 1l2Contenu 3
Contenu vraiment très très très long et d'ailleurs on se demande jusqu'où il va aller 1l3Contenu 3

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 Bloc-notes mdBook.


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

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


À propos de cette page

Création : 18 mars 2023

Dernière version : 23 mars 2023 21:55


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


mdBook : Markdown : Codes dans le texte

Le caractère ` est obtenu avec la combinaison de touches « ALTGR » + « 7 » suivi d'un appui sur « ESPACE » (ou deux fois « 7 » en maintenant « ALTGR » enfoncée).

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 un espace interprété 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é.


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

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


À propos de cette page

Création : 18 mars 2023

Dernière mise à jour : 23 mars 2023 21:57


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


mdBook : 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


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

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


À propos de cette page

Création : 17 mars 2023

Dernière à jour : 23 mars 2023 22:00


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


mdBook : Markdown : Blocs de codes

Le caractère ` est obtenu avec la combinaison de touches « ALTGR » + « 7 » suivi d'un appui sur « ESPACE » (ou deux fois « 7 » en maintenant « ALTGR » enfoncée).

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 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
#![allow(unused)]
#![deny(missing_docs)]

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 :

#![allow(unused)]
#![deny(missing_docs)]

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 « copier » 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 ! ;
  • le « Show hidden » pour afficher des parties de code qui peuvent être masquées pour améliorer la lisibilité. C'est le cas dans notre exemple ici, si vous voulez tester.

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 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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière à jour : 23 mars 2023 22:07


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


mdBook : 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 :

mdBook lien vers la page accueil en local dossier book

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 occurences 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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 23 mars 2023 23:42


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


mdBook : 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 :

Illustration lien chapitre de page mdBook


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 23 mars 2023 23:49


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


mdBook : 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 :

Illustration lien chapitre de page mdBook


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 23 mars 2023 23:59


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


mdBook : 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 .rs (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 bibliothèque par exemple dans le dossier source du projet mdBook Nom-du-projet/src (par défaut).
  • Dans ce dossier bibliothèque, 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 ./bibliothèque/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.

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

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.


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

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


Versions de cette page

Création : 18 mars 2023

Dernière mise à jour : 24 mars 2023 00:09


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


mdBook : 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://happynumeric.fr/images/Bloc-notes-mdBook/bloc-notes-mdbook-markdown-code-ceci-est-une-citation.png)

affiche :

Texte

Stockage des images

Dans l'exemple précédent, j'ai choisi d'utiliser une image en dehors du projet :

  • le projet est dans « https://happynumeric.fr/Bloc-notes-mdBook » ;
  • l'image est dans « https://happynumeric.fr/images/(...) ».

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 :

Texte

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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière version : 24 mars 2023 00:18


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


mdBook : 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 (Markdown) dans un autre fichier .md (Markdown) avec la consigne {{ #include }}.

Il est également possible d'insérer le contenu d'un fichier .rs (code Rust) dans un fichier .md (MarkDown) 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 » (« 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 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 les lignes :

[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 le document 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 pas 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 .rs y sont disponibles.

Par exemple ici : dossier des fichiers de code Rust.

Nous pouvons également proposer des liens vers un fichier particulier par exemple : fichier de code Rust non modifiable

Cela fonctionne sans insérer un fichier .rs

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 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 des possibilités

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


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

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


Versions de cette page

Création : 19 mars 2023

Dernière mise à jour : 19 mars 2023 17:09


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


mdBook : 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.

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

Pour afficher la colonne de numérotation automatique des codes dans le bloc de codes, il convient d'ajouter le mot clef option numbered (= « numéroté ») comme ceci :

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

ce qui qui 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));
}

Nota bene : pour pouvoir afficher la numérotation des lignes du code Rust, nous devons activer l'option editable (= « modifiable ») pour le bloc de code considéré.

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é.

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


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

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


Versions de cette page

Création : 21 mars 2023

Dernière mise à jour : 21 mars 2023 23:37


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


mdBook : Markdown : notes de bas de page

J'ai un souci avec le fonctionnement de cette fonction ici : pour le moment, pour une raison que j'ignore, le compilateur n'incrémente pas le numéro des notes de bas de page. J'ai créé une discussion pour en parler ici : https://happynumeric.fr/phpbb/viewtopic.php?t=104

La documentation officielle indique que les notes de bas de page sont automatiquement placées en bas de page. Ce n'est pas le cas pour le moment ici. J'ai créé une discussion pour en parler ici : https://happynumeric.fr/phpbb/viewtopic.php?t=105

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

  1. insérer le texte « [ ^ note] » (sans espaces) à l'endroit ou l'index doit figurer ;
  2. inserer le texte « [ ^ note] : » (sans espaces) ;
  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.

Du fait de la numérotation automatique, il est préférable d'être scrupuleux dans l'ordre des notes que nous insérons et que nous écrivons.

Par exemple :

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

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

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

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

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

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

[^note]: 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 1.

1

Ceci est la note n°1 associée.

Ceci est un exemple n°2 d'insertion de note de bas de page 1.

1

Ceci est la note n°2 associée.

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

1

Ceci est la note n°3 associée.

1

Ceci est la note n°4 associée.


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

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



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


mdBook 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 :

https://localhost:7777
https://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.


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

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


À propos de cette page

Création : 19 mars 2023

Dernière mise à jour : 23 mars 2023 22:14


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


mdBook : renommage d'une page mdBook

Si nous utilisons mdbook serve, voir le chapitre de page mdBook Consignes pour mdbook serve 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 de bien maîtriser le sujet.

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.

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ée, fonctionne sans avoir besoin d'interrompre mdbook serve.

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.


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

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


À propos de cette page

Création : 20 mars 2023

Dernière mise à jour : 21 mars 2023 01:17


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


mdBook : 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…


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

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


Versions de cette page

Création : 21 mars 2023

Dernière mise à jour : 21 mars 2023 02:48


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


mdBook : 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.


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

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


À propos de cette page

Création : 17 mars 2023

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


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


mdBook : 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.

Astuce : Pour nous en souvenir, je suggère d'écrire une note du type « (laisser en première position du fichier SVP) » que nous pouvons écrire ainsi :

# 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](./mdbook-summary.md-structurer-les-pages-mdbook.md).

Jonction sommaire => pages

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

Cette page est décrire 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, 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.

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.

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 :

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 ou génèrent des erreurs.
  • etc.

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

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


À propos de ce fichier

Création : 17 mars 2023

Dernière mise à jour : 23 mars 2023 19:33


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


mdBook : 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).

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

Le « - » 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.

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

Versions

Création : 15 mars 2023

Dernière mise à jour : 18 mars 2023 01:30


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

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



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


mdBook : 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.


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

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


À propos de cette page

Création 17 mars 2033

Dernière mise à jour : 20 mars 2022 22:56


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


mdBook : 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 sont bien prises en charge.

Le nom

TeSTçœÉçÇ&$€.md

est parfaitement accepté et respecté par exemple.

Je recommande d'utiliser les caractères accentués avec capitales car cela améliore le référencement Web et la lisibilité pour les lecteurs francophones.

## Cas d'une espace : pas de remplacement automatique par un « - »

Par contre, les caractères « ESPACE » ne sont pas acceptés ni remplacés automatiquement par un - par mdBook.

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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 24 mars 2023 00:24


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


mdBook : Dictionnaire anglais français

Dans la mesure où on ne trouve, en dehors de ce Bloc-notes mdBook, 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.

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

français -> anglais

### Sommaire mdBook

Champ d'applicationexpression françaiseexpression anglaisenotes
SUMMARY.mdchapitre du sommaire non numérotéPrefix Chapter ou Suffix Chapter
SUMMARY.mdligne horizontaleSeparator
SUMMARY.mdchapitre du sommaire numérotéNumbered Chapter
SUMMARY.mdrubrique du sommairePart Title
SUMMARY.mdsous-chapitre du sommaireSub Chapter

anglais -> français

Sommaire mdBook

Champ d'applicationexpression anglaiseexpression françaisenotes
SUMMARY.mdDraft Chapterchapitre du sommaire sans lien
SUMMARY.mdNumbered Chapterchapitre du sommaire numéroté avec lien
SUMMARY.mdPart Titlerubrique du sommaire
SUMMARY.mdPrefix Chapterchapitre du sommaire non numéroté avec lienpositionné avant un chapitre du sommaire numéroté
SUMMARY.mdSeparatorligne horizontale
SUMMARY.mdSub Chaptersous-chapitre du sommaire
SUMMARY.mdSuffix Chapterchapitre du sommaire non numéroté avec lienpositionné après un chapitre du sommaire numéroté
SUMMARY.mdTitlePremier #

Note personnelle

Les a priori qui sont faits par l'équipe de développement pour le nommage des éléments du sommaire mdBook ne sont pas des plus pertinents.
Par voie de conséquence, l'approche retenue est amputée de possibilités.
Je propose une approche plus solide des notions de chapitres du sommaire, tout en restant fidèle à ce que propose mdBook dans ma traduction.
J'ai d'autres idées d'améliorations.
Il arrive souvent que je remarque ce genre de manque de profondeur d'analyse et que j'ai rapidement des idées qui la rendraient bien plus pertinente, et par voie de conséquence le produit fini. Cette qualité peut vous être utile si vous faites appel à mes services. Ou pas.


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

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


À propos de cette page

Création : 23 mars 2023

Dernière mise à jour : 23 mars 2023 13:03


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


mdBook : 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

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 — Happy Numeric


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

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


À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 23 mars 2023 22:15


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


mdBook : 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 un « ESPACE », et l'interpréteur / compilateur n'ayant pas prévu ce cas pour le moment (17 mars 2023, v0.4.28), il ne crée pas un titre comme nous l'attendons.

Pour corriger cette erreur, il suffit de supprimer le « ALTGR + ESPACE » et de le remplacer par un « 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-insérés (dossier)
              fichier-inséré.md

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

{{ # include ./mon-dossier/fichier-inséré.md }}

Nous souhaitons écrire un lien qui pointe vers page-mdBook-cible.md dans fichier-à-inséré.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-insérés (dossier)
              fichier-inséré.md

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

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

Autres questions avec réponses

Je vous invite à consulter l'espace dédié à mdBook https://happynumeric.fr/phpbb/viewforum.php?f=122 et à vous inscrire et à participer à ces forums.

mdBook serve : ne crée pas tous les fichiers.md que je déclare dans SUMMARY.md : https://happynumeric.fr/phpbb/viewtopic.php?t=121


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

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


À propos de cette page

Création : 15 mars 2023

Dernière mise à jour : 23 mars 2023 22:22


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


mdBook : 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 :

mdBook Erreur adresse de fichier incorrecte pour un {{ #include }}

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 bloc-notes mdBook, 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 :

mdBook Avertissement adresse de fichier incorrecte pour un {{ #include }} dans un bloc code

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.


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

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


À propos de cette page

Création : 18 mars 2023

Dernière mise à jour : 18 mars 2023 21:18


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


mdBook : Atouts et limites

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 » 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
  • 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.

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 (savoir) que l'outil sera enrichi à l'avenir.

Utiliser mdBook, c'est bénéficier de cette logique de site compilé (« buildé ») et donc plus performant et plus sûr.

Utiliser mdBook, c'est bénéficier de l'outil de compilation et d'exécution de codes Rust intégrés.

« 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.

Et vous, qu'en pensez-vous ?

Parlons-en dans cette discussion : https://happynumeric.fr/phpbb/viewtopic.php?t=101.


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

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


À propos de cette page

Création : 16 mars 2023

Dernière mise à jour : 20 mars 2023 19:10


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


mdBook : 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.


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

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


À propos de cette page

Création : 17 mars 2023

Dernière mise à jour : 19 mars 2023 23:49


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


mdBook : 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.


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

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


À propos de cette page

Création : 14 mars 2023

Dernière mise à jour : 21 mars 2023 22:22

Marc JESTIN, Happy Numeric

Services liés à ce Bloc-notes mdBook

  • Mise en place d'espaces documentaires et communautaires (internes et externes).
  • Construction et rédaction de documentations
  • Formations.

Contact : https://happynumeric.fr/me-contacter.

Autres Services

  • Formation ;
  • Conseil ;
  • Assistance à maîtrise d'ouvrage (pour vous aider à mieux gérer vos intervenants numériques) ;
  • Création de sites Web ;
  • Maintenance préventive (et sécurité) ;
  • Dépannage, réparation ;
  • Assistance à distance et sur site ;
  • secrétariat informatique ;
  • etc.

Contact : https://happynumeric.fr/me-contacter

Autres sites utiles

Sites mdBook

J'ai créé :

Autres outils de création Web

J'ai mis en ligne d'autres sites pour parler de numérique :

Site happynumeric.fr

https://happynumeric.fr

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


Versions de cette page

Date de création : 17 mars 2023

Dernière mise à jour : 22 mars 2023 15:44