Guide Markdown pour les rédacteurs et les développeurs

Personne écrivant sur un ordinateur portable dans un café

Markdown est ce qui se rapproche le plus d'un format d'écriture universel sur internet. Il est utilisé dans les READMEs GitHub, les documents Notion, les messages Slack, les sites de documentation, les articles de blog et les notes des développeurs. Apprenez-le une fois et vous l'utiliserez partout — pour le reste de votre carrière.

Qu'est-ce que Markdown ?

Markdown est un langage de balisage léger créé par John Gruber en 2004. L'idée centrale : écrire en texte brut à l'aide de conventions de ponctuation simples, qui se convertissent en HTML parfaitement mis en forme.

This **bold text** and *italic text* render instantly.

S'affiche ainsi : This bold text and italic text render instantly.

Le texte brut reste parfaitement lisible — même avant le rendu.

Syntaxe de base

Titres

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Utilisez les titres pour créer une hiérarchie dans votre document. # H1 correspond généralement au titre de la page — n'en utilisez qu'un seul par document.

Mise en emphase

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~

Listes

Unordered list:
- Item one
- Item two
  - Nested item (indent with 2 spaces)
  - Another nested item
- Item three

Ordered list:
1. First step
2. Second step
3. Third step

Liens et images

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")

![Alt text for image](https://example.com/image.jpg)
![Alt text](./local-image.png "Optional title")

Citations

> This is a blockquote.
> It can span multiple lines.

> You can nest blockquotes:
> > Like this.

Ligne horizontale

---

(Trois tirets, astérisques ou traits de soulignement ou plus sur leur propre ligne)

Blocs de code

Le code en ligne utilise des guillemets obliques simples :

Use the `console.log()` function for debugging.

Les blocs de code délimités utilisent des triples guillemets obliques avec un identifiant de langage optionnel pour la coloration syntaxique :

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Les langages pris en charge incluent javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust, et des dizaines d'autres — selon le moteur de rendu.

Tableaux

Les tableaux Markdown utilisent des caractères pipe et des tirets :

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

Alignez les colonnes avec des deux-points dans la ligne de séparation :

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Les tableaux font partie de GitHub Flavored Markdown (GFM), et non du Markdown standard. Ils fonctionnent sur GitHub, VS Code, la plupart des plateformes de documentation et MDX.

Listes de tâches (GFM)

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images

S'affiche sous forme de cases à cocher interactives sur GitHub. Largement pris en charge dans les moteurs de rendu Markdown modernes.

Les variantes Markdown

Le Markdown original est volontairement minimaliste. Des extensions se sont multipliées depuis :

Variante	Utilisée dans	Ajouts principaux
CommonMark	Nombreuses plateformes	Spécification standardisée
GitHub Flavored (GFM)	GitHub, GitLab	Tableaux, listes de tâches, barré, liens automatiques
MDX	Sites React	Composants JSX dans Markdown
Pandoc Markdown	Documents académiques	Notes de bas de page, citations, formules
MultiMarkdown	Outils macOS	Tableaux, métadonnées, notes de bas de page

En cas de doute, utilisez GFM — c'est la variante étendue la plus largement prise en charge.

Front matter

De nombreux processeurs Markdown prennent en charge le front matter YAML en haut d'un fichier pour les métadonnées :

---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---

# Article content starts here

Le front matter est analysé séparément du corps du document et utilisé pour des éléments tels que les titres de page, les dates et les métadonnées SEO.

MDX : Markdown + JSX

MDX est un Markdown qui peut contenir des composants React. Il est idéal pour la documentation et les articles de blog sur les sites basés sur React (Next.js, Gatsby, Astro) :

import { Alert } from '../components/Alert'

## Important note

<Alert type="warning">
  This feature is deprecated in v3.
</Alert>

Regular **Markdown** content continues below.

Cela allie la simplicité de Markdown à la puissance des composants interactifs.

Échapper les caractères spéciaux

Faites précéder les caractères spéciaux Markdown d'une barre oblique inverse pour les afficher littéralement :

\*not italic\*
\# not a heading
\[not a link\]

Conseils pour de meilleurs documents Markdown

Une phrase par ligne — Rend les diffs plus lisibles dans Git ; le rendu est identique car Markdown ignore les sauts de ligne simples.
Une ligne vide entre les blocs — Laissez toujours une ligne vide entre les paragraphes, les titres, les listes et les blocs de code.
Marqueurs de liste cohérents — Choisissez - ou * pour les listes non ordonnées et restez-y fidèle dans tout un projet.
Liens de référence pour les URLs répétées — Définissez une fois, utilisez plusieurs fois :
```
See the [documentation][docs] and [changelog][docs].
[docs]: https://example.com/docs
```
Texte alternatif pour chaque image — Indispensable pour l'accessibilité et le SEO.

Vérifier la lisibilité

Markdown facilite l'écriture — mais écrire facilement peut produire un texte difficile à lire. Utilisez notre outil Readability Score pour vérifier le niveau de lecture Flesch-Kincaid, la complexité des phrases et l'usage de la voix passive. Visez un langage clair et concis correspondant à un niveau de lecture de Grade 8–10 pour un public général.

Markdown fait partie de ces outils qui s'apprennent en 10 minutes et se rentabilisent toute une vie. Commencez à l'utiliser dès aujourd'hui — vos futurs collaborateurs (et votre futur vous-même) vous en remercieront.