mdBook : Markdown : mise en garde
Il peut exister des variantes dans les langages Markdown.
Je ne les présente pas toutes ici.
Markdown par défaut
Je recommande de nous attacher à utiliser les codes recommandés par mdBook lorsque nous travaillons avec mdBook.
Dans sa documentation officielle, mdBook renvoie vers la « GitHub Flavored Markdown Spec » (spécification Markdown saveur Github) 1.
À ce jour 13 juillet 2026, il s’agit de la v 0.29 gfm (2019-04-06). 2
Cela ne garantit en rien que le compilateur mdBook est 100 % compatible avec l’intégralité de ce document.
Il est préférable de nous en tenir aux codes et méthodes documentés dans la documentation officielle pour ne pas nous exposer à d’éventuelles difficultés par la suite lors d’une montée de version par exemple.
En effet, la plupart des tests fonctionnels qui sont faits le sont d’abord et avant tout avec les pratiques de la communauté mdBook.
Il est bon d’avoir connaissance des conventions et pratiques autres, mais nous devrions avoir conscience et nous attacher à nous en tenir à celles de l’outil.
J’ai créé ce livre en me référant aux documentations et autres supports mdBook officiels.
Vous ne devriez pas rencontrer de difficultés particulières si vous suivez les indications que j’y donne.
Rester homogène
Lorsque plusieurs symboles sont possibles, le fait de les mélanger n’est pas une bonne idée.
Si nous écrivons nos fichiers sources en mélangeant les symboles, nous risquons d’obtenir de mauvais résultats ou de perdre des contenus dans le projet mdBook une fois compilé.
Exemple de risque (trivial)
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 ! (mais prévisible)
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.
-
GitHub Flavored Markdown Spec (anglais) : https://github.github.com/gfm/ ↩
-
Pas d’évolution depuis la première version de cette page (20 mars 2023). ↩