Markdown a été créé par John Gruber en 2004 avec un objectif unique et élégant : écrire du texte brut qui se lit naturellement, puis le convertir en HTML propre. Deux décennies plus tard, il est partout — fichiers README de GitHub, descriptions de pull requests, messages Slack, docs Notion, articles de blog, réponses de chat IA. C'est l'un de ces outils que vous utiliserez chaque jour pour le reste de votre carrière, que vous y pensiez consciemment ou non.

Ce qu'est réellement Markdown

Markdown est du texte brut avec une syntaxe légère et lisible superposée. Un # en début de ligne devient un <h1>. Entourer un mot de **doubles astérisques** le met en gras. Les backticks produisent du code en ligne. La philosophie de conception centrale est que la source Markdown doit être lisible telle quelle — même avant d'être rendue. Si vous avez déjà écrit un e-mail avec *des astérisques autour de l'emphase* ou utilisé des tirets pour une liste à puces, vous écriviez déjà quelque chose de très proche de Markdown.

Voici un avant-après rapide. Le Markdown à gauche produit le HTML à droite :

markdown
## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.
html
<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

Vous écrivez la partie supérieure ; un processeur Markdown produit la partie inférieure. Cette étape de traduction est invisible une fois qu'elle est dans votre éditeur ou pipeline CI.

Syntaxe de base — La partie que chaque variante partage

Quelle que soit la variante Markdown que vous utilisez, ces éléments de base fonctionnent partout :

  • Titres — # H1, ## H2, ### H3 (jusqu'à six niveaux)
  • Gras et italique — **gras**, *italique*, ***les deux***
  • Liens — [texte du lien](https://url.com)
  • Images — ![texte alternatif](image.png)
  • Code en ligne — `backtick` entoure un extrait ; les triples backticks ouvrent un bloc de code délimité
  • Citations — commencer une ligne par >
  • Listes non ordonnées — lignes commençant par - ou *
  • Listes ordonnées — lignes commençant par 1., 2., etc.
  • Règle horizontale — trois tirets ou plus : ---

Voici un extrait de README réaliste qui utilise tout ce qui précède ensemble :

markdown
# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License
Astuce : vous pouvez utiliser notre outil Aperçu Markdown pour coller n'importe quel Markdown et le voir rendu instantanément — utile pour vérifier la syntaxe avant de pousser vers GitHub.

Le problème des variantes — CommonMark, GFM et autres

Voici le piège : "Markdown" n'est pas une seule chose. La spécification originale de 2004 de Gruber était intentionnellement lâche, ce qui a conduit à des années d'implémentations incompatibles. Différents analyseurs géraient les cas limites — listes imbriquées, lignes vides dans les citations, précédence entre l'emphase et les liens — de façons différentes. Le même fichier source rendrait différemment dans différents outils.

CommonMark (lancé en 2014) a résolu ce problème. Un groupe de développeurs — dont des personnes de GitHub, Stack Overflow et Reddit — a écrit une spécification rigoureuse et sans ambiguïté qui couvrait chaque cas limite avec une suite de tests de 652 exemples. La plupart des outils modernes utilisent maintenant CommonMark comme base.

GitHub a ensuite étendu CommonMark avec ses propres ajouts et publié GitHub Flavored Markdown (GFM). GFM est ce que vous écrivez dans les READMEs, issues et pull requests GitHub. Beaucoup d'autres outils ont également adopté les extensions GFM, mais pas tous — donc ce qui se rend sur GitHub peut ne pas se rendre de la même façon dans votre générateur de site statique ou application de prise de notes. Savoir quelle variante votre outil prend en charge évite beaucoup de grattages de tête.

Extensions GitHub Flavored Markdown

GFM ajoute cinq fonctionnalités sur CommonMark que vous utiliserez constamment sur GitHub et tout outil qui prend en charge le superset GFM :

Tableaux — colonnes délimitées par des pipes avec une ligne séparatrice de tirets :

markdown
| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

Listes de tâches — cases à cocher dans les issues et pull requests :

markdown
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

Texte barré — entourez le texte de doubles tildes :

markdown
~~deprecated API~~ — use `newMethod()` instead

Blocs de code délimités avec indices de langage — l'identifiant de langage après les backticks d'ouverture active la coloration syntaxique :

markdown
```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

Liens automatiques — les URLs brutes comme https://example.com sont automatiquement rendues cliquables sans avoir besoin de la syntaxe [texte](url). C'est pratique dans les commentaires d'issues mais peut être surprenant si vous collez une URL que vous ne voulez pas lier.

Utilisez notre outil Formateur Markdown pour nettoyer les espacements incohérents, normaliser l'indentation des listes et standardiser les délimiteurs de blocs de code délimités — pratique avant de committer des docs dans un dépôt.

Où vous utiliserez Markdown en pratique

Markdown apparaît dans plus d'endroits que la plupart des développeurs ne s'y attendent quand ils le rencontrent pour la première fois :

  • GitHub et GitLab — fichiers README, issues, descriptions de pull requests, wikis et même corps de messages de commit. Chaque dépôt que vous touchez aura au moins un README.md.
  • Générateurs de sites statiques — Jekyll, Hugo, Eleventy, Astro et Next.js acceptent tous des fichiers de contenu Markdown. Vous écrivez des articles dans des fichiers .md et le générateur les convertit en pages HTML au moment de la compilation.
  • Outils de documentation — MkDocs, Docusaurus et GitBook sont entièrement construits autour de sources Markdown. Les bibliothèques open-source utilisent presque universellement l'un d'eux.
  • Applications de prise de notes — Obsidian, Notion, Bear et Typora utilisent tous Markdown comme format natif (avec des extensions variables). Vos notes sont des fichiers texte brut portables, pas une base de données propriétaire.
  • Plateformes CMS — Ghost utilise Markdown nativement. Contentful et Strapi prennent tous deux en charge les champs Markdown. Les configurations CMS headless stockent généralement le contenu long format sous forme de chaînes Markdown.
  • Outils IA — ChatGPT et Claude produisent tous deux du Markdown par défaut. Les extraits de code, les termes en gras et les listes à puces dans les réponses IA sont du Markdown — l'interface de chat les rend, mais le texte sous-jacent est **gras** et ```python.

Markdown vs HTML — Quand utiliser lequel

Markdown se convertit en HTML, mais il ne peut pas tout exprimer que HTML peut. Il n'y a pas d'équivalent pour <div class="card">, les attributs data-*, ou les attributs aria-*. Pour le contenu en prose simple — documentation, READMEs, articles de blog, journaux de modifications — Markdown est plus rapide à écrire et bien plus lisible dans sa forme brute. Pour les composants UI complexes, les mises en page personnalisées, ou les annotations d'accessibilité qui nécessitent des attributs spécifiques, vous avez besoin de HTML.

La bonne nouvelle : la plupart des processeurs Markdown permettent du HTML brut en ligne. Vous pouvez mélanger les deux. Si vous avez besoin d'un <figure> avec un <figcaption>, ou un widget de divulgation <details>, écrivez simplement le HTML directement dans votre fichier .md. Le processeur le transmet sans le modifier. Utilisez cette échappatoire avec parcimonie — si plus d'un tiers de votre fichier est du HTML brut, vous pourriez aussi bien écrire directement en HTML et utiliser notre Formateur HTML pour le garder propre.

  • Utilisez Markdown pour : documentation, READMEs, journaux de modifications, articles de blog, articles de base de connaissances, champs de description d'API
  • Utilisez HTML pour : mise en page précise, composants personnalisés, formulaires, éléments nécessitant des attributs spécifiques
  • Mélangez les deux quand : contenu principalement en prose avec quelques exceptions structurelles (un tableau responsive, une intégration vidéo)

Conclusion

Markdown est trompeusement simple — il ressemble à une poignée de règles de ponctuation, mais il alimente la documentation de pratiquement tous les grands projets open-source. Comprendre la syntaxe de base prend environ dix minutes. Comprendre les différences de variantes (CommonMark vs GFM vs ce que votre SSG utilise) est ce qui sépare les développeurs qui se battent parfois avec leur outillage de documentation de ceux qui ne le font pas.

Les références faisant autorité : CommonMark pour la spécification standardisée, GitHub Flavored Markdown pour les extensions GitHub, et Markdown Guide pour une référence pratique sous forme d'aide-mémoire. Pour l'écriture au quotidien, notre Aperçu Markdown vous permet de voir instantanément la sortie rendue, et le Formateur Markdown maintient la cohérence de vos fichiers source.

← All Markdown articles Browse all categories →