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.

Règles#

La syntaxe est encadrée par un ensemble de règles :

• règles de référence
• règles configurées dans Geotribu

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

---
title: "Titre de ma page dans l'en-tête"
---

# Je suis l'unique titre de niveau 1

## C'est vrai ça, c'est le seul, l'unique

Woa, quel titre !

---
title: "Titre de ma page dans l'en-tête"
---

# Je suis l'unique titre de niveau 1

# Ah ouais ? Eh bah moi aussi je peux être niveau 1 si je veux !

Pfff, encore une guéguerre pour savoir qui a le plus gros niveau de titre :( !

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.

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.  
Surligne nous si tu me crois pas !

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 :

Lizmap est un ensemble de composants logiciels permettant de publier facilement et rapidement un projet QGIS sur le Web. Lizmap se décompose en :
* une extension QGIS permettant de paramétrer le rendu final sur le web
* une application web permettant notamment d'afficher les projets configurés et gérer les utilisateurs

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

- pas bien : https://geotribu.fr/
- bien : <https://geotribu.fr/>
- encore mieux : [texte du lien qui apparaît](https://geotribu.fr/)

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://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 liée à Mkdocs qui intègre, depuis sa version 1.5, un mécanisme de validation au moment de la génération dont la configuration sur le site Geotribu est ici. Ce changement a été opéré sur le site en septembre 2023.

De cette façon, on profite de plusieurs avantages :

• on utilise la syntaxe de Mkdocs et on profite de la validation intégrée
• on peut naviguer entre les contenus depuis un IDE ou GitHub
• on profite des fonctionnalités d'autocomplétion des IDE comme VS Code :

- :name_badge: pas bien : <https://geotribu.fr/rdp/2022/rdp_2022-12-16/#le-mobiliscope>
- :name_badge: pas bien : comme nous le disions dans [cette super news d'une précédente RDP dont le lien est absolu (argh !)](https://geotribu.fr/rdp/2022/rdp_2022-12-16/#le-mobiliscope)
- :negative_squared_cross_mark: ancienne méthode désormais invalide : comme nous le disions dans [cette super news d'une précédente RDP dont le lien part de la racine du site](/rdp/2022/rdp_2022-12-16/#le-mobiliscope)
- :white_check_mark: :white_check_mark: très bien : comme nous le disions dans [cette super news d'une précédente RDP dont le lien est relatif à la page actuelle](../../rdp/2022/rdp_2022-12-16.md#le-mobiliscope)

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)

Commentaires