C'est quoi Markdown, et pourquoi il a gagné ?
Markdown est un langage de balisage léger : tu écris du texte brut avec quelques symboles conventionnels, et ça se transforme en HTML mis en forme. **gras** devient gras, # Titre devient un titre. C'est toute l'idée.
Créé par John Gruber en 2004, il a écrasé toutes les alternatives plus lourdes pour trois raisons simples :
- C'est du texte brut. Pas de format propriétaire, pas de fichier binaire. N'importe quel éditeur sur n'importe quel OS peut l'ouvrir, pour toujours.
- C'est lisible même sans rendu. Un fichier Markdown se comprend à l'état brut — contrairement à du HTML ou du LaTeX.
- C'est versionnable. Les diffs Git sur du Markdown sont propres et lisibles, et c'est pour ça que les développeurs l'ont adopté pour la documentation.
Aujourd'hui, c'est le format par défaut des README GitHub, des docs techniques, des apps de notes comme Notion et Obsidian, des générateurs de sites statiques (Hugo, Astro, Jekyll) — et l'article que tu lis a été écrit en Markdown.
La syntaxe de base : source vs rendu
Voici tout ce que tu utiliseras au quotidien. Tu peux tester chaque exemple en direct dans l'Éditeur Markdown avec l'aperçu côte à côte.
Titres
# H1 — un seul par document, en général le titre
## H2 — sections principales
### H3 — sous-sections
Six niveaux existent (# à ######), mais un document bien structuré dépasse rarement le H3.
Emphase
*italique* ou _italique_
**gras** ou __gras__
***gras italique***
Listes
- Élément non ordonné
- Autre élément
- Élément imbriqué (indente de 2 espaces)
1. Élément numéroté
2. Deuxième élément
Astuce sympa : la numérotation n'a pas besoin d'être juste dans la source. 1. / 1. / 1. s'affiche 1, 2, 3 — le moteur compte pour toi, donc réordonner tes éléments ne casse jamais la liste.
Liens et images
[Texte du lien](https://exemple.com)
Une image, c'est juste un lien avec un ! devant. Le texte alternatif compte pour l'accessibilité et le SEO — ne le laisse pas vide.
Code
Le code en ligne utilise des backticks simples : `const x = 1`. Pour les blocs, utilise les blocs de code délimités par trois backticks, avec un tag de langage optionnel pour la coloration syntaxique :
```javascript
function saluer(nom) {
return `Salut, ${nom} !`;
}
```
Citations
> Ceci s'affiche comme une citation.
> Plusieurs lignes restent dans le même bloc.
GitHub Flavored Markdown : les extras que tout le monde utilise
La spec originale de 2004 avait des trous, alors GitHub Flavored Markdown (GFM) les a comblés. Ces extensions sont maintenant supportées quasiment partout.
Tableaux
| Fonctionnalité | Markdown de base | GFM |
|----------------|:----------------:|----:|
| Tableaux | Non | Oui |
| Tâches | Non | Oui |
La deuxième ligne contrôle l'alignement : :--- à gauche, :---: centré, ---: à droite.
Listes de tâches
- [x] Écrire le brouillon
- [ ] Le relire
- [ ] Publier
GitHub les affiche comme de vraies cases à cocher — interactives dans les issues et les pull requests.
Texte barré
~~ancienne approche~~
La grande antisèche
Mets ce tableau en favori — il couvre 95 % du Markdown quotidien :
| Élément | Syntaxe | Notes |
|---|---|---|
| Titre | ## Texte | 1 à 6 symboles # |
| Gras | **texte** | |
| Italique | *texte* | |
| Barré | ~~texte~~ | GFM |
| Liste à puces | - élément | Aussi * ou + |
| Liste numérotée | 1. élément | Numéros auto-corrigés |
| Liste de tâches | - [ ] élément | GFM |
| Lien | [texte](url) | |
| Image |  | |
| Code en ligne | `code` | |
| Bloc de code | ```lang | Le langage active la coloration |
| Citation | > texte | Imbricable avec >> |
| Tableau | | a | b | | GFM, ligne de séparation requise |
| Séparateur | --- | Seul sur sa ligne |
| Retour à la ligne | Deux espaces en fin de ligne | Ou ligne vide pour un nouveau paragraphe |
| Échappement | \*pas italique\* | Antislash devant les caractères spéciaux |
Où Markdown est vraiment utilisé
- Les fichiers README. Chaque projet GitHub, GitLab ou npm en attend un. Si tu démarres un projet, le Générateur de README te sort un fichier bien structuré (badges, installation, usage, licence) en quelques minutes.
- Les sites de documentation. Docusaurus, Starlight, MkDocs et compagnie avalent des fichiers Markdown et produisent des sites complets.
- Les apps de notes. Obsidian stocke du
.mdpur ; Notion l'importe et l'exporte ; Bear, Logseq et Joplin sont nativement Markdown. - Les générateurs de sites statiques. Hugo, Jekyll, Astro : les articles de blog sont des fichiers Markdown avec un bloc de frontmatter en haut.
- Les outils de chat. Slack et Discord supportent un sous-ensemble proche du Markdown (
*gras*sur Slack, les blocs ``` sur Discord) — assez proche pour que tes réflexes fonctionnent. - Les présentations. Les outils basés sur Marp ou reveal.js transforment un fichier Markdown en slides — teste avec Markdown Slides, où
---sépare chaque diapositive.
Et quand tu dois passer d'un monde à l'autre : Markdown vers HTML convertit ton fichier en balisage propre pour un email ou un champ de CMS, et HTML vers Markdown fait l'inverse — pratique pour migrer de vieilles pages web vers un dépôt de docs.
Les pièges classiques
Les retours à la ligne ne marchent pas comme tu crois. Appuyer une fois sur Entrée ne crée pas de saut de ligne visible dans la plupart des moteurs de rendu. Il te faut soit deux espaces en fin de ligne, soit une ligne vide complète pour démarrer un nouveau paragraphe. C'est la source numéro 1 des « mon Markdown s'affiche mal ».
L'indentation des listes imbriquées est capricieuse. Certains parseurs veulent 2 espaces, d'autres 4. Si un élément imbriqué s'affiche à plat, ajoute de l'indentation jusqu'à ce que ça marche — et ne mélange jamais tabulations et espaces.
Les caractères spéciaux doivent être échappés. Tu veux un astérisque littéral ? Écris \*. Pareil pour _, #, | (dans les tableaux) et les backticks.
Le HTML brut marche parfois, parfois non. La plupart des moteurs acceptent du HTML en ligne comme <br> ou <details>, mais les environnements filtrés (commentaires, chat) le suppriment. N'en dépends pas pour des documents portables.
Un mot sur les dialectes
Il n'existe pas de standard Markdown « officiel » unique — la spec d'origine était ambiguë, donc des dialectes sont apparus. CommonMark est la spécification rigoureuse que les parseurs modernes implémentent ; GFM, c'est CommonMark plus les tableaux, listes de tâches, texte barré et liens automatiques ; MultiMarkdown et Pandoc Markdown ajoutent des fonctionnalités académiques (notes de bas de page, citations). En pratique : écris du CommonMark + GFM et tes documents s'afficheront correctement presque partout.
À toi de jouer
La façon la plus rapide d'apprendre Markdown, c'est de taper et de regarder le rendu. Ouvre l'Éditeur Markdown — aperçu en direct, coloration syntaxique, export HTML ou PDF. Gratuit, dans ton navigateur, sans compte.