Markdown est un format de texte qui permet d'écrire des documents structurés avec une syntaxe courte et lisible. Un texte marqué en Markdown se transforme ensuite en HTML, en PDF, ou en à peu près n'importe quel autre format.
Sa force tient à une contrainte : le fichier source reste du texte brut. Vous pouvez l'ouvrir dans n'importe quel éditeur, le relire sans outil spécialisé, et le versionner dans un dépôt Git sans conflit de mise en forme.
Ce guide part des bases et progresse vers les syntaxes avancées.
Paragraphes et retours à la ligne
Un paragraphe est une suite de lignes séparées par une ligne vide. C'est la seule séparation qui compte :
Ceci est un paragraphe.
Même avec un retour à la ligne,
le texte reste dans le même paragraphe.
Ceci est un second paragraphe.Une ligne vide au milieu d'un paragraphe le coupe en deux. C'est le mécanisme le plus simple et le plus important.
Pour forcer un retour à la ligne à l'intérieur d'un paragraphe, terminez la ligne par deux espaces, ou par une barre oblique inverse. La seconde solution est préférable : les espaces en fin de ligne sont invisibles et disparaissent souvent lors d'un copier-coller.
Titres
Le nombre de dièses détermine le niveau du titre.
# Niveau 1
## Niveau 2
### Niveau 3
#### Niveau 4Deux règles à respecter :
- Un seul titre de niveau 1 par document, celui qui nomme la page.
- Ne sautez pas de niveau : passez de
##à####est une erreur, car les lecteurs d'écran utilisent cette hiérarchie pour construire la table des matières.
Vous pouvez fermer un titre avec des dièses en fin de ligne. C'est facultatif, et cela sert surtout à rendre la source plus lisible :
## Un titre bien visible ##Texte en emphase
Quatre notations, dont une n'appartient pas au Markdown de base.
*Italique* ou _Italique_
**Gras** ou __Gras__
***Gras italique***
~~Barré~~Les deuxièmes formes existent pour rester compatibles avec des syntaxes historiques. Préférez les premières, plus faciles à repérer.
Le barré, obtenu avec deux tildes, fait partie des extensions GFM, détaillées plus bas.
Listes
Trois types, distingués par leur marqueur.
- Puce niveau 1
- Puce niveau 1, suite
- Imbriquée niveau 2
- Imbriquée niveau 3
1. Étape 1
2. Étape 2
1. Sous-étapeDeux listes doivent être séparées par une ligne vide, faute de quoi Markdown absorbe la première puce de la seconde liste dans la liste précédente.
Les listes à puces acceptent -, * ou +. Choisissez-en une et gardez-la.
Pour les listes numérotées, tous les items peuvent porter le chiffre 1. : le
rendu les renumérote automatiquement, ce qui évite les décalages après un ajout
ou une suppression.
Listes de tâches
- [x] Rédiger le texte
- [ ] Relire
- [ ] PublierLe rendu produit des cases à cocher, visuellement interactives, mais sans effet réel : cocher une case ne modifie pas le fichier. Cette syntaxe vient également de GFM.
Liens
La forme de base associe un texte affiché à une destination :
[Next.js](https://nextjs.org)
Le titre au survol s'écrit entre guillemets, après l'URL :
[Next.js](https://nextjs.org "Le framework Next.js")
Une adresse seule devient automatiquement un lien, ainsi qu'une adresse entourée d'angles :
https://example.com
<https://example.com>
La deuxième forme est préférable : elle échappe correctement les caractères qui casseraient le rendu, comme les parenthèses.
Les liens de référence séparent la destination du texte, ce qui évite de répéter la même URL :
Consulter [la documentation][docs].
[docs]: https://example.com/documentation
Images
La syntaxe reprend celle des liens, avec un point d'exclamation devant.
Le texte entre crochets est le texte alternatif. Il s'affiche si l'image ne
charge pas, et c'est ce que lisent les lecteurs d'écran. Rédigez-le comme une
description, pas comme un nom de fichier. Un pont.jpg n'apprend rien ; un
"Pont suspendu au-dessus d'une rivière, au coucher du soleil" est utile.
Pour contrôler la taille, certains dialectes acceptent une syntaxe étendue, avec une accolade après le chemin :
Citations
Un chevron marque le début du bloc cité.
> Le texte cité peut s'étendre
> sur plusieurs lignes.
>
> Les lignes vides deviennent un nouveau paragraphe.
On peut imbriquer une citation dans une liste ou une autre citation, en ajoutant un chevron supplémentaire.
Code
Le code est le point où Markdown se distingue nettement du HTML. Deux formes.
Sur une ligne, avec des accents graves :
Utilisez la commande `pnpm install`.Sur plusieurs lignes, avec trois accents graves, en indiquant le langage après l'ouverture :
```python
def slugify(titre: str) -> str:
return titre.lower().replace(" ", "-")
```Le nom du langage n'est pas décoratif : il détermine la coloration syntaxique.
Utilisez un identifiant précis (python, typescript, bash, json) plutôt
qu'un terme vague comme code ou text, sinon vous n'obtiendrez aucune
coloration.
Pour afficher du texte contenant des accents graves, entourez le bloc de quatre accents graves.
Le code indenté de quatre espaces est aussi reconnu comme bloc de code par le Markdown de base, mais cette écriture est fragile : une tabulation ou un espace en trop change la signification. Préférez les accents graves.
Filets horizontaux
Trois caractères sur une ligne isolée insèrent une séparation visuelle :
---Le même effet avec trois astérisques ou trois traits bas. Dans la plupart des dialectes, une ligne de cette forme tout en haut du document est interprétée comme un bloc de métadonnées, et non comme un filet.
Tableaux
Les tableaux sont une extension GFM, absente du Markdown de base. La syntaxe emploie des barres verticales et une ligne de séparation :
| Colonne A | Colonne B |
| --------- | --------- |
| Cellule 1 | Cellule 2 |
| Cellule 3 | Cellule 4 |Les deux caractères de chaque bord de ligne sont facultatifs :
Colonne A | Colonne B
--------- | ---------
Cellule 1 | Cellule 2L'alignement se règle sur la ligne de séparation :
| Gauche | Centre | Droite |
| :----- | :----: | -----: |Si vous utilisez des tableaux dans un contexte où GFM n'est pas disponible, vérifiez le rendu. Une solution de repli consiste à écrire une liste, qui reste lisible partout.
Échappement
Certains caractères déclenchent une interprétation. Pour en afficher un litérallement, précédez-le d'une barre oblique inverse.
\*Ce texte n'est pas en italique\*
\# Ce symbole n'est pas un titreLes caractères à échapper le plus souvent sont : *, _, `, #, [,
], >, ainsi que les barres verticales dans un tableau.
L'échappement est surtout nécessaire dans les zones où la syntaxe est interprétée à tort : à l'intérieur d'un paragraphe qui parle de Markdown.
Dialectes : la nuance importante
Markdown n'est pas une norme unique, mais un socle plus une collection d'extensions. Deux implémentations peuvent donc se comporter différemment sur le même texte.
CommonMark est la spécification de référence. Elle définit le noyau : titres, emphase, listes, liens, images, citations, code, filets. Tout constructeur conforme à cette norme produit le même rendu.
GFM (GitHub Flavored Markdown) ajoute les tableaux, le barré, les listes de tâches et le lien automatique des adresses. C'est le dialecte le plus répandu, car GitHub et la plupart des plateformes d'édition l'utilisent.
MDX autorise des composants programmables dans le document. Un élément écrit entre chevrons et accolades est rendu par une application plutôt que converti en HTML.
La conséquence pratique : avant d'utiliser une syntaxe avancée, vérifiez que le moteur qui rendra votre document la supporte. Le graphe ci-dessous est généré avec KaTeX, une syntaxe elle aussi propre à une extension :
$$
e^{i\pi} + 1 = 0
$$Pièges fréquents
Espaces en fin de ligne. Invisibles, ils sont supprimés par de nombreux outils. Pour un retour à la ligne forcé, utilisez une barre oblique inverse.
Liste collée à une liste. Une liste qui suit un paragraphe sans ligne vide est absorbée dans ce paragraphe, et ne s'affiche pas comme une liste.
Chevrons non échappés. Un chevron suivi d'un mot ressemble à une balise HTML et peut disparaître du rendu. Écrivez-le entre accents graves, ou échappez-le.
Accents graves imbriqués. Impossible d'inclure un accent grave dans du code sur une ligne sans utiliser deux accents graves de chaque côté, avec un espace intermédiaire.
Faux titres. Une ligne finissant par --- sous un paragraphe produit un
titre de niveau 2 (la syntaxe Setext), et non un filet.
Bonnes pratiques
Une idée par paragraphe. Le formatage ne rattrape pas une structure défaillante. Si un paragraphe dépasse cinq lignes, scindez-le.
Ne mettez pas en valeur tout ce qui peut l'être. Un document où chaque mot est en gras n'a plus d'accent. Réservez le gras aux notions centrales.
Écrivez des liens descriptifs. Préférez « la documentation de Next.js » à « cliquez ici ». Le lecteur comprend la destination avant de cliquer, et le texte reste utile hors contexte.
Décrivez vos images. Le texte alternatif est une obligation d'accessibilité, pas un champ facultatif.
Reliez vos documents. Une référence vers un article antérieur prolonge la lecture et aide le lecteur à trouver la suite.
Restez lisible dans la source. La syntaxe doit se comprendre en relisant le fichier. Si une construction devient illisible, elle est probablement trop compliquée.
Pour aller plus loin
La spécification CommonMark fournit une description exhaustive de chaque construction et de ses cas limites. Les guides de syntaxe de GitHub et de Pandoc couvrent les extensions propres à chaque dialecte et leurs interactions.
Un test simple, si vous écrivez dans un format dérivé : collez votre texte dans un éditeur qui propose un aperçu du rendu, et comparez avec ce que vous attendez.