Markdown : guide complet avec cheatsheet et pièges à éviter

Si vous savez écrire ceci, vous maîtrisez 80% de Markdown :

## Titre

Texte **gras**, *italique*, `code inline`.

- Liste item 1
- Liste item 2

> Citation importante

[Lien](https://exemple.com)

```bash
echo "bloc de code"
```

Ce guide vous apprend la syntaxe complète, les différences entre variantes (CommonMark, GFM, Pandoc), et les pièges fréquents qui cassent votre mise en forme.

Aller à : C’est quoi ? · Cheatsheet · Pièges · Docs-as-code

C’est quoi Markdown ?

Imaginons que vous écrivez un email. Vous voulez mettre un mot en gras ou créer une liste. Dans Word, vous cliquez sur des boutons. En HTML, vous écrivez des balises <strong> ou <ul>. C’est lourd.

Markdown résout ce problème : vous écrivez du texte quasi-normal, et il se transforme automatiquement en page web formatée.

Avant/après : la différence visuelle

Ce que vous écrivez (Markdown)	Ce que vous voyez (rendu)
**important**	important
*italique*	italique
- item	• item
[lien](https://blog.stephane-robert.info)	lien
`code`	code

Glissez pour voir

Pourquoi Markdown a été inventé ?

En 2004, John Gruber (avec les contributions d’Aaron Swartz) crée Markdown avec un objectif simple : écrire pour le web sans connaître HTML.

L’idée géniale : le texte source doit être lisible tel quel, même sans rendu. Comparez :

HTML (illisible)	Markdown (lisible)
<h2>Titre</h2>	## Titre
<strong>gras</strong>	**gras**
<a href="url">lien</a>	[lien](url)
<ul><li>item</li></ul>	- item

Glissez pour voir

Où utilise-t-on Markdown aujourd’hui ?

Markdown est devenu le standard de facto pour la documentation technique :

Contexte	Exemples
Développement	README, CHANGELOG, documentation de code
Plateformes	GitHub, GitLab, Stack Overflow, Reddit
Blogs techniques	Dev.to, Hashnode, ce blog
Notes personnelles	Obsidian, Notion, Logseq
Documentation	Docusaurus, Starlight, MkDocs

Glissez pour voir

Le super-pouvoir de Markdown

Un fichier Markdown (.md) est un simple fichier texte. Vous pouvez l’ouvrir avec n’importe quel éditeur, le versionner avec Git, le lire sans logiciel spécial. C’est pour ça que les développeurs l’adorent.

Markdown vs autres formats

Format	Avantages	Inconvénients
Markdown	Simple, portable, versionnable	Limité pour mise en page complexe
HTML	Contrôle total	Verbeux, difficile à lire
Word/Google Docs	WYSIWYG, familier	Binaire, pas versionnable, vendor lock-in
LaTeX	Parfait pour maths/publications	Courbe d’apprentissage raide

Glissez pour voir

Règle simple : si votre contenu est du texte structuré (documentation, articles, notes), Markdown est probablement le meilleur choix.

Quelle variante de Markdown utilisez-vous ?

Markdown a un “problème” : il existe plusieurs variantes. Le Markdown original de 2004 était volontairement minimaliste. Depuis, chaque plateforme a ajouté ses propres extensions.

Conséquence pratique : une syntaxe qui marche sur GitHub peut ne pas fonctionner ailleurs. Avant d’écrire, identifiez votre contexte.

Variante	Où l’utiliser	Spécificités
CommonMark	Standard portable	Base stricte, sans ambiguïté
GFM (GitHub Flavored)	GitHub	Tables, task lists, autolinks, footnotes
GLFM (GitLab Flavored)	GitLab	Similar à GFM + extensions GitLab
Pandoc	Conversion multi-formats	Extensions riches (citations, métadonnées)
MDX	Astro, Next.js, Docusaurus	Composants JSX dans Markdown

Glissez pour voir

Règle simple

• GitHub → visez GFM (spec officielle)
• GitLab → visez GLFM (documentation)
• Documentation portable → visez CommonMark
• Site statique moderne → visez MDX

CommonMark vs GFM : ce qui change vraiment

Pensez à CommonMark comme le Markdown de base (le socle commun), et à GFM comme une version enrichie avec des bonus.

Analogie : CommonMark = français standard. GFM = français + argot parisien. Tout le monde comprend le français standard, mais certaines expressions ne marchent qu’à Paris.

Fonctionnalité	CommonMark	GFM	GLFM
Titres, emphase, listes	✅	✅	✅
Blocs de code avec langage	✅	✅	✅
Liens et images	✅	✅	✅
Tableaux	❌	✅	✅
Task lists - [x]	❌	✅	✅
Strikethrough ~~texte~~	❌	✅	✅
Autolinks (URLs cliquables)	❌	✅	✅
Footnotes [^1]	❌	✅	✅
Mermaid diagrams	❌	✅	✅
Math LaTeX $x^2$	❌	✅	✅

Glissez pour voir

Piège courant

Si votre tableau ou task list ne s’affiche pas, vérifiez que votre moteur supporte GFM. Un éditeur Markdown basique (CommonMark strict) ne les rendra pas.

Cheatsheet : les 12 syntaxes essentielles

Voici les 12 syntaxes que vous utiliserez 90% du temps. Apprenez-les dans l’ordre : les premières sont les plus fréquentes.

1. Titres (niveaux 1 à 6)

# Titre niveau 1 (h1)
## Titre niveau 2 (h2)
### Titre niveau 3 (h3)
#### Titre niveau 4 (h4)

Bonne pratique

Un seul # (h1) par document — c’est le titre principal. Commencez vos sections par ##.

2. Emphase (gras, italique, barré)

Syntaxe	Rendu	Compatibilité
**gras** ou __gras__	gras	✅ Universel
*italique* ou _italique_	italique	✅ Universel
~~barré~~	barré	GFM/GLFM
***gras italique***	gras italique	✅ Universel

Glissez pour voir

3. Liens et images

[Texte du lien](https://url.com)
[Texte du lien](https://url.com "Titre au survol")

![Texte alternatif](chemin/image.png)
![Alt](image.png "Légende")

Exemple : [Documentation Git](/docs/developper/version/git/) crée un lien interne.

4. Listes à puces

- Premier élément
- Deuxième élément
  - Sous-élément (indentation cohérente)
  - Autre sous-élément
- Troisième élément

Rendu :

• Premier élément
• Deuxième élément
  • Sous-élément (indentation cohérente)
  • Autre sous-élément
• Troisième élément

Piège fréquent

L’indentation compte. Pour les sous-listes, indentez de façon cohérente (2 ou 4 espaces selon votre convention). L’important : la sous-liste doit être plus à droite que le texte de l’item parent.

5. Listes numérotées

1. Premier
2. Deuxième
3. Troisième

Astuce : vous pouvez utiliser 1. partout, Markdown renumérote automatiquement :

1. Premier
1. Deuxième
1. Troisième

6. Task lists (GFM/GLFM)

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

Rendu (sur GitHub/GitLab) :

• Tâche terminée
• Tâche à faire
• Autre tâche

7. Code inline et blocs de code

Code inline : entourez de backticks simples.

Utilisez la commande `kubectl get pods` pour lister les pods.

Bloc de code : utilisez trois backticks avec le langage.

```bash
#!/bin/bash
echo "Hello DevOps"
kubectl get pods -n production
```

Coloration syntaxique

Spécifiez toujours le langage après les backticks : bash, yaml, json, python, javascript, dockerfile, etc. Cela active la coloration.

8. Tableaux (GFM/GLFM)

| Colonne 1 | Colonne 2 | Colonne 3 |
|-----------|:---------:|----------:|
| Gauche    | Centré    | Droite    |
| Données   | Données   | Données   |

Rendu :

Colonne 1	Colonne 2	Colonne 3
Gauche	Centré	Droite
Données	Données	Données

Glissez pour voir

Alignement :

• :--- aligné à gauche (défaut)
• :---: centré
• ---: aligné à droite

9. Citations (blockquotes)

> Ceci est une citation.
> Elle peut s'étendre sur plusieurs lignes.
>
> > Et même être imbriquée.

Rendu :

Ceci est une citation. Elle peut s’étendre sur plusieurs lignes.

Et même être imbriquée.

10. Séparateurs horizontaux

Trois tirets, astérisques ou underscores créent une ligne horizontale :

---
***
___

11. Échappement des caractères spéciaux

Pour afficher un caractère Markdown littéralement, préfixez-le d’un backslash :

\*Ceci n'est pas en italique\*
\# Ceci n'est pas un titre

Caractères à échapper : \ ` * _ { } [ ] ( ) # + - . ! |

12. Notes de bas de page

Voici une affirmation importante[^1].

[^1]: Source de l'affirmation avec lien.

Rendu : Voici une affirmation importante[^1].

Compatibilité footnotes

Fonctionne si le moteur active l’extension footnotes : GitHub (depuis septembre 2021), GitLab, Pandoc, certains SSG. Pas en CommonMark strict.

Pièges fréquents et solutions

Même les développeurs expérimentés tombent dans ces pièges. La bonne nouvelle : une fois que vous les connaissez, vous ne vous ferez plus avoir.

Piège 1 : le retour à la ligne ne fonctionne pas

Problème : vous appuyez sur Entrée, mais le texte reste sur la même ligne.

Première ligne
Deuxième ligne

Rendu (collé) : Première ligne Deuxième ligne

Solutions :

Deux espaces

Ajoutez deux espaces à la fin de la ligne :

Première ligne··
Deuxième ligne

(Les ·· représentent deux espaces invisibles)

Balise BR

Utilisez <br> explicitement :

Première ligne<br>
Deuxième ligne

Ligne vide

Séparez par une ligne vide (crée un nouveau paragraphe) :

Première ligne

Deuxième ligne

Piège 2 : la liste imbriquée casse

Problème : votre sous-liste ne s’affiche pas correctement.

- Item 1
 - Sous-item (indentation insuffisante)

Solution : indentez de façon cohérente. La sous-liste doit être plus à droite que le texte de l’item parent. Utilisez 2 ou 4 espaces selon votre convention :

- Item 1
  - Sous-item (aligné correctement)

Piège 3 : le bloc de code sort de la liste

Problème : le code apparaît en dehors de la liste.

1. Étape 1
```bash
echo "code"
```

Solution : ajoutez une ligne vide après l’item, puis indentez le bloc de code pour qu’il soit visuellement aligné sous le texte de l’item :

1. Étape 1

    ```bash
    echo "code"
    ```

Piège 4 : le tableau ne rend pas

Causes possibles :

Symptôme	Cause	Solution
Tableau en texte brut	Moteur non-GFM	Vérifier la compatibilité
Colonnes décalées	Pipes `	` manquants
Pas de ligne d’en-tête	Ligne `	---

Glissez pour voir

Structure minimale obligatoire :

| Col1 | Col2 |
|------|------|
| A    | B    |

Piège 5 : les caractères spéciaux cassent le rendu

Problème : *, _, #, [ interprétés comme syntaxe.

Solution : échappez avec \ :

Le fichier \*.log contient les erreurs.
Prix : 10\$ (pas 10$)

Markdown pour la documentation DevOps

En tant que professionnel DevOps/DevSecOps, vous écrirez énormément en Markdown. Voici les cas d’usage principaux.

README de projet

Structure type d’un bon README :

# Nom du projet

Description en une phrase.

## Installation

```bash
pip install mon-projet
```

## Utilisation

```bash
mon-projet --help
```

## Configuration

| Variable | Description | Défaut |
|----------|-------------|--------|
| `API_KEY` | Clé d'API | - |

## Contribuer

Voir [CONTRIBUTING.md](CONTRIBUTING.md).

Runbooks et procédures

## Procédure : restart service en production

### Prérequis

- Accès SSH au serveur
- Droits sudo

### Étapes

1. Vérifier l'état actuel :

    ```bash
    systemctl status mon-service
    ```

2. Redémarrer :

    ```bash
    sudo systemctl restart mon-service
    ```

3. Valider :

    ```bash
    curl -I https://mon-service.local/health
    ```

### Rollback

Si le service ne répond pas après 2 min, restaurer la version précédente.

Docs-as-Code : versionner sa documentation

L’approche docs-as-code traite la documentation comme du code :

• Stockée dans Git (versionnée, historique, branches)
• Revue en Pull Request (relecture, commentaires)
• Lintée automatiquement (markdownlint, vale)
• Déployée en CI/CD (preview, publication)

# Installer markdownlint pour valider votre Markdown
# https://www.npmjs.com/package/markdownlint-cli
npm install -g markdownlint-cli

# Linter un fichier
markdownlint README.md

# Linter tout un dossier
markdownlint docs/

Checklist docs-as-code :

• README structuré (Installation, Usage, Configuration)
• Linter Markdown en CI (markdownlint, vale)
• Preview automatique en PR
• Déploiement automatique au merge

Workflow recommandé

1. Écrire en Markdown dans votre IDE
2. Commit + Push sur une branche
3. Ouvrir une PR pour review
4. CI vérifie le lint + génère une preview
5. Merge → publication automatique

Outils et éditeurs recommandés

Catégorie	Exemples
Éditeur avec preview	VS Code, Zed, Obsidian, Typora
Linter	markdownlint-cli, vale
Convertisseur	Pandoc (vers PDF, DOCX, HTML)
Diagrammes	Mermaid, Excalidraw, PlantUML

Glissez pour voir

Support Mermaid

Les diagrammes Mermaid sont supportés nativement dans les fichiers Markdown sur GitHub et GitLab. Pour d’autres plateformes, vérifiez la documentation.

À retenir

1. Markdown = texte lisible même sans rendu, idéal pour la documentation versionnée.

2. Identifiez votre variante : CommonMark (portable), GFM (GitHub), GLFM (GitLab), MDX (sites modernes).

3. Les 5 syntaxes les plus utilisées : titres ##, emphase **gras**, listes -, code ```, liens []()

4. Pièges majeurs : retours à la ligne, indentation des listes, blocs de code dans les listes.

5. Spécifiez toujours le langage des blocs de code pour la coloration syntaxique.

6. Docs-as-code : versionnez votre documentation dans Git, lintez avec markdownlint, reviewez en PR.

Prochaines étapes

Docs-as-Code Traitez votre documentation comme du code

Git pour la gestion de versions Versionnez votre code et votre documentation

FAQ - Questions Fréquemment Posées

Qu'est-ce que Markdown et pourquoi l'utiliser ?

Markdown est un langage de balisage léger créé en 2004 par John Gruber. Il permet d'écrire du texte formaté (gras, listes, liens) avec une syntaxe simple et lisible. Idéal pour README, documentation technique et blogs car versionnable avec Git.

Quelle est la différence entre CommonMark, GFM et GLFM ?

CommonMark est le standard Markdown portable de base. GFM (GitHub Flavored Markdown) ajoute tableaux, task lists, footnotes et Mermaid. GLFM (GitLab Flavored Markdown) est similaire à GFM avec des extensions GitLab spécifiques.

Pourquoi mon retour à la ligne ne fonctionne pas en Markdown ?

En Markdown, un simple retour à la ligne (Entrée) ne crée pas de saut visible. Solutions : ajouter deux espaces à la fin de la ligne, utiliser la balise HTML <br>, ou séparer par une ligne vide pour créer un nouveau paragraphe.

Comment créer un tableau en Markdown ?

Les tableaux Markdown nécessitent GFM ou GLFM (pas CommonMark). Structure : en-têtes séparés par pipes |, ligne de séparation |---|, puis données. Alignement : :--- gauche, :---: centré, ---: droite.

Comment mettre du code dans une liste numérotée Markdown ?

Pour inclure un bloc de code dans une liste numérotée, ajoutez une ligne vide après l'item, puis indentez le bloc de code (généralement 4 espaces) pour qu'il soit visuellement aligné sous le texte de l'item parent.

Quels outils utiliser pour écrire et valider du Markdown ?

Éditeurs recommandés : VS Code (avec extension Markdown All in One), Obsidian, Typora. Pour valider : markdownlint-cli (npm install -g markdownlint-cli). Pour convertir : Pandoc transforme Markdown en PDF, DOCX ou HTML.

Comment échapper les caractères spéciaux en Markdown ?

Pour afficher un caractère Markdown littéralement (*, _, #, [, etc.), préfixez-le d'un backslash. Exemple : \* affiche * au lieu de déclencher l'italique. Caractères à échapper : \ ` * _ { } [ ] ( ) # + - . ! |

×

📖 Voir la documentation →