Aller au contenu

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

logo markdown

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
---
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 !
1
2
3
4
5
6
7
8
9
---
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.

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

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

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/>
- encore mieux : [texte du lien qui apparaît](https://geotribu.fr/)

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 :


Contributions à cette page : Julien Moura

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


Commentaires

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