Rédiger en Markdown : règles et enjeux de qualité#
Pour rappel, la syntaxe Markdown a vocation à être transformée in fine en HTML. Etant donné que c'est une syntaxe extensible aux multiples implémentations différentes, son rendu dépend donc de l'outil utilisé pour visualiser le résultat :
- l'onglet
Preview
de GitHub, - un éditeur de texte (Visual Studio Code, Sublime Text, HackMD, Hedgedoc, vim...)
- le générateur de site MkDocs / Material.
C'est ce dernier qui fait foi.
Cette page détaille les principes de la rédaction en Markdown pour Geotribu.
En savoir plus
Consulter l'article "Comprendre le rendu Markdown".
Règles#
La syntaxe est encadrée par un ensemble de règles :
Quelques règles de base sont listées ci-dessous, notamment celles pour lesquelles il y a fréquemment des erreurs.
Unicité du titre de niveau 1#
Le Markdown étant destiné à être du HTML, il ne peut y avoir qu'un titre de niveau 1 défini par balise #
. Il peut cependant y avoir un titre alternatif défini dans l'en-tête via la clé title:
et qui est utilisé dans le menu de navigation.
Référence : MD025 - Multiple top-level headings in the same document
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
Cohérence du caractère pour les listes à puces#
S'il est techniquement possible d'utiliser différents caractères, il est préférable d'utiliser le même caractère (généralement l'astérisque ou le tiret). A minima le style doit être cohérent dans une même page.
Dans cet exemple, des astérisques (*
) ont été utilisés après que des tirets (-
) l'aient déjà été pour le même niveau de puces.
Référence : MD004 - Unordered list style
Paragraphes#
En markdown, selon les implémentations, il est important de laisser des lignes vides entre les différents paragraphes (ou ce qui deviendra une balise HTML différente une fois converti). Par exemple :
- entre le texte et le début d'une liste (ordonnée ou pas)
- entre un titre et un paragraphe
- entre une image et un texte
Interligne simple#
Pour revenir à la ligne sans créer de nouveau paragraphe, il suffit d'ajouter deux espaces à la fin de la ligne.
1 2 3 4 5 6 |
|
Je suis la première ligne du paragraphe. Et moi la ligne suivante mais du coup, je suis à la suite !
Je suis un nouveau paragraphe.
Je suis la deuxième ligne du deuxième paragraphe, séparée de la précédente avec un simple interligne car la ligne précédente a 2 espaces à la fin.
Listes à puces#
Pour les mêmes raisons, le premier élément d'une liste à puces doit être précédé d'une ligne vide (ce n'est pas le cas pour GitHub, où les deux formes sont acceptées). Par exemple, si on n'insère pas de ligne vide entre le paragraphe et le premier élément d'une liste à puces, le rendu ne fonctionnera pas :
1 2 3 |
|
Référence : MD032 - Lists should be surrounded by blank lines
Déclaration explicite des liens hypertextes#
Si la plupart des outils repèrent les liens dans le texte, il est recommandé de les déclarer explicitement, notamment si le document est destiné à être intégré dans un format plus exigeant en termes de formatage (mail, etc.).
Référence : MD034 - Bare URL used
1 2 3 |
|
- pas bien : https://geotribu.fr/
- bien : https://geotribu.fr/
- bien : texte du lien qui apparaît
Liens internes relatifs#
Quand il s'agit de lier les contenus entre eux, par exemple pour pointer sur une précédente revue de presse ou un article, il ne faut pas utiliser l'URL absolue vers le contenu mais le chemin relatif.
Cela permet :
- de garder les contenus indépendants de l'URL de publication du site qui a tour à tour été http://geotribu.net, https://geotribu.net et https://static.geotribu.fr et qui pourrait encore être amenée à changer.
- d'éviter les liens cassés en cas de renommage/déplacement d'un contenu
Cette règle est spécifique à Geotribu et est contrôlée via un script exécuté à chaque publication du site
1 2 3 4 |
|
pas bien : https://static.geotribu.fr//rdp/2022/rdp_2022-12-16/#le-mobiliscope
pas bien : comme nous le disions dans cette super news d'une précédente RDP dont le lien est absolu (argh !)
bien : comme nous le disions dans cette super news d'une précédente RDP dont le lien part de la racine du site
bien : comme nous le disions dans cette super news d'une précédente RDP dont le lien est relatif à la page actuelle
Outillage#
Pour favoriser l'adoption de ces règles et contrôler leur application, plusieurs outils sont mis en place dans le processus de contribution :
- l'outil de vérification de la syntaxe (linter) Markdown,
markdownlint-cli
est configuré (voir la page dédiée) - des scripts automatiques au moment des contributions : les git hooks (voir la page dédiée)
-
étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub. ↩