Rédiger en Markdown : règles et enjeux de qualité#

Règles#

L'outil markdownlint a défini un ensemble de règles dont nous utilisons une partie et des régales spécifiques :

• règles de référence
• règles configurées dans Géotribu

Vérifier la syntaxe avec markdownlint-cli#

On utilise l'outil en ligne de commande développé en node :

1
2
3
4
5

# installation du package
yarn add markdownlint-cli --dev --non-interactive --no-lockfile --prefer-offline

# vérification sur les fichiers contenus dans les dossiers commençant par '202'
yarn markdownlint -i "**/template_*.md" "content/*/202*/**/*.md"

Il est aussi possible d'utiliser markdownlint sous forme d'extension dans Visual Studio Code.

Erreurs fréquentes#

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) et 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

Sauts de ligne et lignes vides#

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

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

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