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: 28 mai 2021
Créé: 14 septembre 2020
Contributions à cette page : Julien Moura

Ce contenu est sous licence Creative Commons BY-NC-SA 4.0 International


Commentaires

Une version minimale de la syntaxe markdown est acceptée pour la mise en forme des commentaires.
Propulsé par Isso.
Retour en haut de la page