Aller au contenu

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

Note

Les règles à appliquer dépendent du moteur de rendu (conversion en HTML) utilisé. Consulter l'article "Comprendre le rendu Markdown" pour en savoir plus.

Règles

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

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.

erreur style 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

capture liste à puces

Référence : MD032 - Lists should be surrounded by blank lines


Dernière mise à jour: 14 septembre 2020
Contributions à cette page : Julien Moura

Commentaires