Aide-mémoire Markdown : toute la syntaxe utile, avec exemples

Qu'est-ce que le Markdown ?

Le Markdown est un langage de balisage léger créé par John Gruber en 2004. Son objectif est simple : un texte facile à lire tel quel, qui se convertit proprement en HTML. C'est aujourd'hui la norme pour les fichiers README, la documentation, les forums de développeurs, les applications de prise de notes comme Obsidian, les messageries comme Slack et Discord, et de nombreuses plateformes de blog.

Le dialecte le plus répandu est le GitHub Flavored Markdown (GFM), qui ajoute à la syntaxe d'origine les tableaux, les listes de tâches, le texte barré et les liens automatiques.

Titres

# Titre 1
## Titre 2
### Titre 3
#### Titre 4

Utilisez un seul titre # par document (le titre principal), et respectez l'ordre des niveaux. Mettez toujours un espace après le #.

Mise en valeur

Markdown	Résultat
**gras**	gras
*italique* ou _italique_	italique
***gras italique***	gras italique
~~barré~~	barré (GFM)
`code en ligne`	code en ligne

Liens et images

[Texte du lien](https://example.com)
[Lien avec titre](https://example.com "Texte au survol")
<https://example.com>

![Texte alternatif décrivant l'image](image.png)

[Lien par référence][docs]
[docs]: https://example.com/docs

Rédigez un texte alternatif pertinent pour les images. Il est lu à voix haute par les lecteurs d'écran et aide les moteurs de recherche à comprendre l'image.

Listes

- Élément à puce
- Autre élément
  - Élément imbriqué (retrait de 2 espaces)

1. Première étape
2. Deuxième étape
3. Troisième étape

- [x] Tâche terminée
- [ ] Tâche à faire

Les listes de tâches (- [ ]) font partie du GFM et s'affichent sous forme de cases à cocher sur GitHub et dans de nombreux éditeurs.

Citations

> Ceci est une citation.
>
> Elle peut s'étendre sur plusieurs paragraphes.

Blocs de code

```js
function greet(name) {
  return `Bonjour, ${name} !`;
}
```

Entourez le code de trois accents graves et ajoutez le nom du langage (js, python, bash, json…) pour que la coloration syntaxique puisse s'appliquer.

Tableaux

| Outil       | Catégorie | Prix     |
| :---------- | :-------: | -------: |
| Résumé      | Texte     | Gratuit  |
| OCR         | Images    | Gratuit  |

Les deux-points de la ligne de séparation règlent l'alignement : :--- à gauche, :---: centré, ---: à droite. Les colonnes n'ont pas besoin d'être alignées dans la source ; cela facilite simplement la lecture.

Séparateurs et sauts de ligne

Trois tirets seuls sur une ligne créent un séparateur :

---

Terminez une ligne par deux espaces (ou une barre oblique inversée)\
pour forcer un saut de ligne dans un paragraphe.

Une ligne vide commence un nouveau paragraphe. La plupart des problèmes de mise en forme viennent de lignes vides manquantes entre paragraphes, listes et titres.

Échapper les caractères spéciaux

Pour afficher un symbole que le Markdown interpréterait, placez une barre oblique inversée devant : \*pas en italique\*, \#pas un titre, \[pas un lien\].

Essayez en direct et exportez en HTML

1. Ouvrez l'éditeur Markdown vers HTML gratuit.
2. Tapez du Markdown, ou utilisez la barre d'outils pour les titres, le gras, les liens, les listes, les tableaux et le code.
3. Regardez l'aperçu se mettre à jour pendant la frappe. Passez à l'onglet HTML pour voir le code généré.
4. Copiez le HTML, téléchargez une page .html complète ou enregistrez votre fichier .md.

Votre brouillon est enregistré automatiquement dans votre navigateur, et rien n'est envoyé.

Astuces Markdown

• Laissez des lignes vides autour des titres, listes, blocs de code et tableaux.
• Soyez cohérent : choisissez - ou * pour les puces et tenez-vous-y.
• Utilisez des liens relatifs dans les dépôts ([Installation](docs/setup.md)) pour qu'ils fonctionnent sur chaque branche.
• Prévisualisez avant de publier. Les plateformes diffèrent légèrement dans les extensions qu'elles prennent en charge.
• Utilisez du HTML si nécessaire. La plupart des moteurs Markdown acceptent du HTML en ligne pour ce que le Markdown ne sait pas faire, comme <kbd> ou <details>, même si certaines plateformes le retirent par sécurité.

Questions fréquentes

Quelle différence entre Markdown et GitHub Flavored Markdown ?

Le GFM est une extension du Markdown standard (CommonMark) qui ajoute les tableaux, les listes de tâches, le texte barré et les liens automatiques.

Comment souligner du texte en Markdown ?

Le Markdown n'a pas de syntaxe de soulignement, car un texte souligné ressemble à un lien. Si vous en avez vraiment besoin, utilisez du HTML : <u>texte</u>.

Comment faire un saut de ligne sans nouveau paragraphe ?

Terminez la ligne par deux espaces ou une barre oblique inversée, ou utilisez <br>.

Le HTML exporté est-il sûr à utiliser sur mon site ?

Oui. Le HTML exporté est un balisage propre et sémantique, sans styles en ligne, et l'aperçu est assaini pour bloquer les scripts.

En résumé

Une douzaine de symboles couvrent presque tout ce que vous écrirez en Markdown. Gardez cet aide-mémoire sous la main, laissez des lignes vides entre les blocs et prévisualisez votre texte avant de le publier.