Skip to content

Markdown Aide-mémoire

Langage de balisage léger pour du texte mis en forme.

01

Premiers pas

Titres et paragraphes

Utilisez # pour les titres (niveaux 1 à 6). La syntaxe alternative utilise === pour H1 et --- pour H2. Les paragraphes nécessitent une ligne vide entre eux. Markdown est conçu pour rester lisible en texte brut.

markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

Sauts de ligne

Deux espaces en fin de ligne ou un antislash créent un saut de ligne dur (<br>). Sans eux, un simple retour à la ligne est un retour souple qui fusionne en un seul paragraphe. Laissez toujours une ligne vide pour séparer les paragraphes.

markdown
First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

Commentaires

Markdown n'a pas de syntaxe de commentaire officielle, mais les commentaires HTML (<!-- -->) fonctionnent dans la plupart des moteurs de rendu et sont masqués dans la sortie. L'astuce [//]: # utilise une référence de lien vide pour ajouter des notes. Les commentaires restent visibles dans le texte source.

markdown
<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

Espaces et indentation

Quatre espaces en début de ligne transforment le texte en bloc de code — méfiez-vous des indentations accidentelles. L'indentation compte pour les listes imbriquées (2 à 4 espaces par niveau). Les tabulations sont généralement traitées comme 4 espaces. Utilisez les espaces de manière cohérente pour éviter des problèmes de rendu entre moteurs.

markdown
Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

Lignes horizontales

Trois tirets, astérisques ou underscores consécutifs ou plus créent une ligne horizontale (<hr>). Les tirets sont les plus courants. Les espaces entre les caractères sont autorisés. Par clarté, entourez les lignes horizontales de lignes vides. Ne confondez pas --- (ligne) avec # (titre).

markdown
---

***

___

   * * *

Text above

---

Text below
02

Mise en forme du texte

Gras (bold & strong)

Double astérisque ou underscore produit du gras (<strong>). Les astérisques sont préférés car les underscores ne fonctionnent pas au milieu d'un mot (snake_case). Vous pouvez imbriquer d'autres emphases dans le gras. Les balises HTML <strong> servent de solution de repli.

markdown
**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

Italique (em)

Astérisque ou underscore simple crée de l'italique (<em>). Les astérisques fonctionnent au milieu d'un mot ; les underscores traitent les underscores internes au mot comme littéraux (donc no_italic_here). Utilisez <em> en repli. L'italique sert à l'emphase, pas seulement au style.

markdown
*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

Gras + italique combinés

Triple astérisque/underscore produit à la fois du gras et de l'italique. Vous pouvez aussi les imbriquer : du gras contenant de l'italique ou inversement. L'ordre n'a pas d'importance pour le rendu mais doit rester cohérent pour la lisibilité.

markdown
***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

Barré (strikethrough)

Double tilde (~~) crée du texte barré, une extension GitHub Flavored Markdown désormais largement prise en charge. Les balises HTML <del> et <s> sont des équivalents en repli. Le Markdown standard (original) n'inclut pas le barré.

markdown
~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

Marquage / surlignage

Le double signe égal (==) pour le surlignage est une extension prise en charge par certains moteurs (pas dans le cœur de GFM). La balise HTML <mark> fonctionne partout. Utilisez le surlignage avec parcimonie pour attirer l'attention sur des termes clés — l'abus réduit son effet.

markdown
==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

Indice et exposant

Les syntaxes tilde (indice) et caret (exposant) (~ ~ et ^ ^) sont des extensions absentes du Markdown standard et de GFM — prises en charge par Pandoc, R Markdown et quelques autres. Pour un support universel, utilisez les balises HTML <sub> et <sup> ou des caractères Unicode.

markdown
H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions
03

Listes

Listes non ordonnées

Utilisez -, * ou + pour les éléments de liste non ordonnée — choisissez-en un et restez cohérent (- est le plus courant). Indentez de 2 à 4 espaces pour les éléments imbriqués. Mélanger les marqueurs dans la même liste peut poser problème dans certains moteurs. Un élément par ligne.

markdown
- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

Listes ordonnées

Les listes ordonnées utilisent des nombres suivis d'un point. Les nombres réels n'ont pas besoin d'être séquentiels — Markdown les renumérote. Pour commencer à un nombre précis, utilisez ce nombre en premier (10. commence à 10). Utilisez 1. pour tous les éléments pour une numérotation automatique.

markdown
1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

Listes imbriquées

Indentez les éléments imbriqués de 2 à 4 espaces (4 est le plus sûr pour des types mixtes). Vous pouvez mélanger des listes ordonnées et non ordonnées à différents niveaux. L'imbrication profonde (3 niveaux et plus) nuit à la lisibilité — envisagez de restructurer. Gardez l'indentation cohérente.

markdown
1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

Listes de tâches

La syntaxe des listes de tâches (- [x] et - [ ]) est une extension GitHub Flavored Markdown. La case à cocher devient interactive sur GitHub/GitLab. Fonctionne avec les listes ordonnées et non ordonnées. Idéal pour les README, les trackers d'issues et le suivi de progression.

markdown
- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

Listes lâches vs serrées

Si les éléments de liste sont séparés par des lignes vides, la liste est « lâche » (chaque élément enveloppé dans <p>). Sans lignes vides, elle est « serrée » (pas d'enveloppe <p>). Cela affecte l'espacement dans la sortie HTML. Ajoutez des lignes vides délibérément pour contrôler l'enveloppage des paragraphes.

markdown
- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

Liste avec plusieurs paragraphes

Pour inclure plusieurs paragraphes ou éléments blocs dans un élément de liste, indentez la suite de 4 espaces (ou alignez avec le contenu du marqueur de liste). Les lignes vides séparent les sous-blocs. C'est essentiel pour les structures de listes complexes mais facile à rater.

markdown
- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item
05

Images

Image de base

La syntaxe d'image ressemble à celle des liens mais préfixée de !. Le texte alternatif est requis pour l'accessibilité — il décrit l'image pour les lecteurs d'écran et s'affiche si l'image ne charge pas. Le chemin peut être relatif, absolu ou une URL. Le titre est optionnel.

markdown
![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

Image avec texte alternatif

Le texte alternatif doit être significatif et concis — décrivez le rôle de l'image, pas juste « image ». Pour les images décoratives, un alt vide (alt='') est acceptable pour indiquer aux lecteurs d'écran de les ignorer. N'utilisez jamais « image de » ou « photo de » — les lecteurs d'écran l'annoncent déjà.

markdown
![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

Images cliquables

Enveloppez une image dans un lien en imbriquant la syntaxe d'image dans celle du lien : [![alt](img)](url). Courant pour les vignettes qui mènent aux versions pleine taille, les badges qui pointent vers le statut CI, et les logos qui ramènent à l'accueil. Gardez un texte alternatif décrivant la destination, pas seulement l'image.

markdown
[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

Images par référence

Les images par référence utilisent le même style de référence que les liens, préfixé de !. Définissez la référence d'image une fois et réutilisez-la. Utile quand la même image apparaît plusieurs fois ou pour garder lisibles les paragraphes chargés d'images.

markdown
![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

Dimensions d'image et figure

Le Markdown standard n'a pas de syntaxe de redimensionnement — utilisez HTML <img> avec les attributs width/height. Les largeurs en pourcentage permettent un dimensionnement responsive. La combinaison <figure> + <figcaption> fournit des légendes sémantiques (HTML5). Certains Markdown étendus (Pandoc) supportent ![alt](img){width=300}.

markdown
<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>
06

Code en ligne et échappement

Code en ligne

Enveloppez le code en ligne dans des backticks simples. Pour montrer des backticks dans du code, utilisez des backticks doubles comme délimiteur (ou plus). Le code en ligne est rendu en monospace et n'est pas interprété comme Markdown. Idéal pour les noms de fichiers, commandes et identifiants de code.

markdown
Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

Échapper les backticks dans les spans de code

Pour inclure un backtick dans un span de code, utilisez plus de backticks comme délimiteurs qu'il n'y en a à l'intérieur : double backticks autour d'un backtick simple. Hors des spans de code, échappez un backtick avec un antislash. La clôture fermante doit égaler la longueur d'ouverture.

markdown
To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

Spans de code et espaces

Les spans de code préservent exactement les espaces internes. Une astuce courante : entourez le contenu d'une espace de début/fin pour afficher des espaces de début/fin qui seraient sinon supprimés. Une espace de chaque côté est retirée automatiquement.

markdown
`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

Échappement par antislash

L'antislash échappe les caractères Markdown spéciaux : backtick, astérisque, underscore, accolades, crochets, parenthèses, dièse, plus, moins, point, point d'exclamation et l'antislash lui-même. L'échappement rend le caractère littéralement. N'échappez que les caractères qui seraient sinon interprétés comme du formatage.

markdown
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

Caractères à échapper

Voici les caractères échappables en Markdown. Tous ne nécessitent pas d'échappement partout — # ne compte qu'en début de ligne, - dans le contexte de liste, etc. Dans le doute, échappez. Les accolades et parenthèses ne nécessitent généralement un échappement que dans des contextes spécifiques (liens, template strings).

markdown
\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation
07

Blocs de code

Blocs de code indentés

Une indentation de 4 espaces (ou une tabulation) crée un bloc de code. Les blocs indentés manquent de coloration syntaxique et de balise de langage. Ils ne peuvent pas être utilisés dans les éléments de liste (traités comme continuation). Préférez les blocs de code clôturés pour les nouveaux contenus — les blocs indentés sont un héritage (legacy).

markdown
Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

Blocs de code clôturés

Triple backticks ou triple tildes créent des blocs de code clôturés (fenced). Les clôtures sont préférées aux blocs indentés — sans ambiguïté et avec indication de langage. Les tildes (~~~) sont utiles quand le code contient lui-même des triple backticks. Fermez toujours la clôture avec le même nombre de caractères.

markdown
```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

Coloration syntaxique

Ajoutez un identifiant de langage juste après la clôture d'ouverture pour la coloration syntaxique (ex. js, python). La plupart des moteurs utilisent highlight.js ou Prism. Alias courants : js, ts, py, rb, sh, json, html, css. Si le langage est inconnu, omettez-le pour du monospace simple.

markdown
```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

```python
def greet(name):
    print(f"Hello, {name}!")
```

```bash
echo "Hello, $USER"
```

Clôtures de code imbriquées

Pour afficher des backticks dans un bloc de code, utilisez une clôture différente (tildes pour du contenu avec backticks, ou plus de backticks qu'il n'y en a à l'intérieur). Quatre backticks clôturent un contenu contenant des triple backticks. La clôture fermante doit égaler la longueur d'ouverture.

markdown
Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

Code dans les listes

Les blocs de code clôturés dans les éléments de liste doivent être indentés pour s'aligner avec le texte de la liste (généralement 3 espaces pour les listes -, 4 pour les listes 1.). Les blocs indentés dans les listes nécessitent 8 espaces (4 pour la liste + 4 pour le code). Bien aligner est l'une des tâches Markdown les plus délicates.

markdown
1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).
08

Citations (blockquote)

Citation simple

Le caractère > démarre une citation en bloc (blockquote). Vous pouvez préfixer chaque ligne ou seulement la première — la plupart des moteurs joignent les lignes consécutives. Les blockquotes sont rendus comme des citations indentées et stylées (<blockquote>). Utilisez-les pour les citations, encadrés et extraits à mettre en valeur.

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

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

Citation multi-lignes

Utilisez des lignes > vides pour séparer les paragraphes dans une citation (sinon ils fusionnent). Le > sur une ligne vide maintient la citation ouverte. Sans lignes vides entre les paragraphes, le texte coule comme un seul paragraphe. Terminez toujours par une ligne normale.

markdown
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

Citations imbriquées

Plusieurs caractères > créent des citations imbriquées (>> pour deux niveaux, >>> pour trois). Ajoutez des espaces pour la lisibilité. L'imbrication profonde (3 niveaux et plus) devient difficile à lire et styliser — préférez l'aplat. Chaque niveau ajoute une indentation dans la sortie HTML.

markdown
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

Citations avec d'autres éléments

Les blockquotes peuvent contenir la plupart des éléments Markdown : titres, listes, code, emphase, même tableaux. Préfixez chaque ligne de > (et une espace) pour les garder dans la citation. Cela rend les blockquotes puissants pour les encadrés, mais le contenu complexe exige un alignement soigné des >.

markdown
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

Citation avec attribution

Markdown n'a pas de syntaxe formelle de citation. Conventions courantes : préfixez l'auteur d'un tiret cadratin sur une nouvelle ligne, ou utilisez HTML <blockquote> avec <footer> et <cite> pour des citations sémantiques. Pour des citations académiques, envisagez une note de bas de page avec la source.

markdown
> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>
09

Tableaux

Tableau simple

Les tableaux utilisent des pipes (|) pour séparer les colonnes et des tirets pour séparer l'en-tête. La ligne d'en-tête est requise. Les pipes aux bords de ligne sont optionnelles mais améliorent la lisibilité. La largeur des colonnes importe peu — les cellules se redimensionnent. Les tableaux sont une extension GitHub Flavored Markdown.

markdown
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

Alignement des cellules

Les deux-points dans la ligne de séparation contrôlent l'alignement : :--- gauche, :---: centre, ---: droite. Sans deux-points, l'alignement par défaut est à gauche. L'alignement s'applique à toute la colonne et définit le CSS text-align dans la sortie HTML. Utile pour les colonnes numériques (alignées à droite) et les en-têtes (centrés).

markdown
| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

Tableau avec mise en forme

Les cellules peuvent contenir du Markdown en ligne : gras, italique, code, liens, barré, emoji. Les éléments blocs (titres, listes, blocs de code) ne fonctionnent pas dans les cellules — utilisez HTML si nécessaire. Gardez un contenu de cellule court pour la lisibilité. Échappez les pipes avec un antislash pour afficher des pipes littérales.

markdown
| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

Tableau complexe

Les tableaux s'adaptent à de nombreuses lignes et colonnes mais restent simples par cellule. Pour des spans de code avec virgules, enveloppez dans des backticks. Échappez les pipes littérales avec un antislash et une pipe. Les données complexes (cellules multi-lignes, tableaux imbriqués) exigent HTML <table>. Envisagez une liste si le tableau devient trop large.

markdown
| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

Astuces et limites des tableaux

Les tableaux Markdown sont limités : pas de fusion de cellules, pas de contenu multi-lignes, pas d'éléments blocs, pas de tableaux imbriqués. Pour cela, utilisez du HTML brut. Gardez les tableaux petits et balayables d'un coup d'œil. Si un tableau nécessite des notes ou du texte long, scindez-le. Des outils comme TablesGenerator.com aident à les construire rapidement.

markdown
| A | B |
|---|---|
| 1 | 2 |

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>
10

Notes de bas de page

Notes simples

Les notes de bas de page utilisent des marqueurs [^id] dans le texte et [^id]: définition ailleurs. L'id peut être un nombre ou un mot. Les moteurs créent des exposants cliquables et une section de notes en bas. Pris en charge par GFM, Pandoc et la plupart des moteurs modernes.

markdown
Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

Références multiples

Une note de bas de page peut être référencée plusieurs fois — chaque [^id] pointe vers la même définition. Les lignes de continuation de la définition sont indentées. La première référence reçoit généralement l'exposant numéroté ; les suivantes pointent vers la même note.

markdown
Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

Notes en ligne

Les notes en ligne (^[text]) intègrent le contenu directement à la référence, prises en charge par Pandoc et certaines extensions (pas dans le cœur de GFM). Elles gardent tout au même endroit mais peuvent casser le flux de lecture. Utilisez-les pour des notes courtes ; les longues valent mieux comme références.

markdown
Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

Positionnement des notes

Les définitions de notes peuvent être placées n'importe où dans le document — les moteurs les collectent et les affichent à la fin. Indentez les lignes de continuation (4 espaces). Les notes fonctionnent dans les blockquotes et les éléments de liste. La position dans la source n'affecte pas la position en sortie.

markdown
Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

Notes avec code et mise en forme

Les définitions de notes supportent le Markdown en ligne (gras, italique, code) et le contenu multi-paragraphes (indentez les lignes de continuation de 4 espaces). Les blocs de code indentés dans les notes nécessitent 8 espaces. Restez concis — le contenu technique long vaut mieux dans le texte principal ou une annexe.

markdown
See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote
11

Listes de définitions

Liste de définitions simple

Les listes de définitions utilisent un terme sur une ligne, puis deux-points (:) suivis de la définition. Prises en charge par PHP Markdown Extra, Pandoc et certaines extensions (pas dans le cœur de GFM). Rendu en <dl><dt><dd>. Utile pour les glossaires et les paires terme-définition.

markdown
Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

Termes multiples

Plusieurs termes consécutifs (sans deux-points) peuvent partager une même définition. Chaque terme devient un <dt>, la définition un <dd>. Utile quand un concept porte plusieurs noms ou alias. Gardez chaque terme sur sa propre ligne.

markdown
CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

Descriptions multiples

Plusieurs définitions consécutives (chacune commençant par deux-points) pour un même terme créent plusieurs éléments <dd>. Utile pour lister plusieurs sens ou aspects distincts d'un terme. Chaque ligne à deux-points est une entrée de définition séparée.

markdown
Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

Listes de définitions imbriquées

Les listes de définitions imbriquées exigent d'indenter la liste interne (2 à 4 espaces) dans la définition externe. Le support varie selon les moteurs — tous ne gèrent pas l'imbrication. Pour des structures de termes hiérarchiques complexes, envisagez HTML <dl> pour la fiabilité. Testez dans votre moteur cible.

markdown
Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

Listes de définitions avec éléments blocs

Les entrées de listes de définitions peuvent contenir plusieurs paragraphes, blockquotes et blocs de code — indentez le contenu de continuation de 4 espaces (au-delà des deux-points). Les blocs de code internes nécessitent 8 espaces au total. C'est puissant mais fragile ; le contenu complexe est plus sûr en HTML <dl>.

markdown
Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)
12

Table des matières

Sommaire automatique

La plupart des moteurs ne génèrent pas de sommaire par défaut. Certains (marked avec le plugin toc, MDX) supportent les placeholders [TOC] ou {:toc}. Des outils comme Doctoc et markdown-toc les génèrent depuis les titres. Pour les sites statiques, des composants TOC lisent les ancres des titres au build ou au runtime.

markdown
## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

Sommaire manuel

Un sommaire manuel est une liste imbriquée de liens vers les ancres des titres. Les ids d'ancres dérivent du texte des titres (minuscules, tirets pour les espaces, ponctuation supprimée). Indentez pour refléter la hiérarchie des titres. Mettez à jour manuellement quand les titres changent, ou utilisez un générateur.

markdown
# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

Règles de génération des ancres

La génération d'ancres varie selon les moteurs. Règles courantes : minuscules, espaces en tirets, ponctuation supprimée, caractères alphanumériques conservés. GitHub conserve les emoji et certains unicode. Les nombres et points sont souvent supprimés. En cas de doute, inspectez le HTML rendu pour trouver l'id réel.

markdown
## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

IDs d'ancres personnalisés

Pour des ancres fiables, ajoutez des IDs explicites. La syntaxe d'attribut {#id} fonctionne dans Pandoc, marked et certaines extensions. L'astuce HTML <a id="..."> fonctionne partout — placez-la avant ou dans le titre. Les IDs personnalisés survivent aux changements de texte des titres.

markdown
## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

Navigation du sommaire et liens de retour

Les liens de retour en haut améliorent la navigation dans les documents longs. Le HTML <details>/<summary> crée un sommaire repliable — idéal pour les sidebars ou les README longs. Combinez avec des liens d'ancres pour une navigation fluide. Ajoutez scroll-margin-top en CSS pour compenser les en-têtes fixes.

markdown
## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>
13

Emoji et caractères spéciaux

Shortcodes d'emoji

Les shortcodes d'emoji (:name:) sont pris en charge par GitHub/GitLab (avec le jeu EmojiOne/Twemoji). Il existe des milliers d'emoji nommés. Les shortcodes sont pratiques mais peu portables — ils peuvent s'afficher littéralement dans les moteurs non GFM. Utilisez des emoji Unicode bruts pour une compatibilité maximale.

markdown
:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

Emoji courants

La plupart des éditeurs et moteurs modernes gèrent directement les emoji Unicode bruts — collez-les simplement. Les shortcodes sont spécifiques à GitHub. Les emoji peuvent transmettre ton et statut (check/cross pour les résultats, bug pour les bugs). Avec parcimonie dans les docs formels ; parfaits dans les README et changelogs.

markdown
:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

Entités HTML

Les entités HTML fonctionnent en Markdown car il passe au HTML. Utilisez &amp; pour les esperluettes littérales (surtout dans les URLs/attributs), &lt; &gt; pour les chevrons, &copy; &reg; &trade; pour les symboles. Les formes numériques (&#169;) et hexadécimales (&#x00A9;) couvrent tout caractère Unicode.

markdown
&amp;  &lt;  &gt;  &quot;  &apos;

&copy;  &reg;  &trade;

&mdash; &ndash; &hellip;

&#169;  &#x00A9;

Use &amp; to show a literal &.

Caractères spéciaux

Markdown ne convertit pas la ponctuation simple en caractères typographiques (guillemets intelligents) par défaut — utilisez des entités HTML ou collez de l'Unicode. Tirets cadratins et guillemets typographiques améliorent la typographie. Beaucoup d'éditeurs les corrigent automatiquement. Pour les flèches et symboles, les entités sont les plus claires.

markdown
-- em dash (or &mdash;)
-- en dash (or &ndash;)
... ellipsis (or &hellip;)
' ' curly quotes (&lsquo; &rsquo;)
" " curly quotes (&ldquo; &rdquo;)
-> arrow (or &rarr;)
(tm) (r) (c)

Combiner emoji et Markdown

Les emoji se combinent avec tous les éléments Markdown : titres, listes, gras, liens, blockquotes. Ils ajoutent des repères visuels aux changelogs, README et templates d'issues. Restez cohérent dans l'usage des emoji (par exemple, gardez une convention de changelog). Évitez les emoji dans l'écriture formelle/académique.

markdown
## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)
14

Diagrammes Mermaid

Flowchart Mermaid

Mermaid est un langage de diagrammes textuel rendu par GitHub, GitLab et de nombreux générateurs de sites statiques. Enveloppez le code Mermaid dans un bloc clôturé mermaid. flowchart TD (haut-bas) ou LR (gauche-droite) définit la direction. Les nœuds utilisent [], {}, () pour différentes formes.

markdown
```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Diagramme de séquence Mermaid

Les diagrammes de séquence montrent les interactions entre participants dans le temps. ->> est une flèche pleine (requête), -->> une flèche pointillée (réponse). participant déclare les acteurs. Utile pour documenter les flux API, protocoles et passage de messages. Rendu automatiquement sur GitHub.

markdown
```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Diagramme de classes Mermaid

Les diagrammes de classes modélisent les structures orientées objet. + signifie public, - privé, # protégé. <|-- dénote l'héritage. Mermaid supporte associations, compositions et interfaces. Idéal pour documenter l'architecture du code directement en Markdown.

markdown
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

Diagramme d'états Mermaid

Les diagrammes d'états montrent les transitions d'état. [*] marque les états début/fin. Les flèches étiquettent les transitions avec des événements (state --> state: event). Utile pour documenter protocoles, états UI et cycle de vie des objets. stateDiagram-v2 est la syntaxe moderne.

markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Diagramme de Gantt Mermaid

Les diagrammes de Gantt visualisent les plannings de projet. dateFormat règle l'analyse des dates. Les tâches utilisent id, start, duration (ex. 7d). 'after a1' enchaîne les tâches. Les sections regroupent les tâches liées. Utile pour les README et plans de projet — rendu automatiquement sur GitHub sans outil externe.

markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Diagramme circulaire Mermaid

Les diagrammes circulaires montrent des proportions en pourcentages (les valeurs sont relatives). Le titre est optionnel. Libellés entre guillemets, valeurs après les deux-points. Mermaid supporte aussi les git graphs, diagrammes ER, journey maps et mind maps — tous rendables en Markdown sur les plateformes compatibles.

markdown
```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```
15

GitHub Flavored Markdown

Listes de tâches (GFM)

Les listes de tâches GitHub Flavored Markdown (GFM) rendent des cases à cocher interactives sur GitHub. [x] cochée, [ ] décochée. Elles fonctionnent dans les issues, PR, commentaires et README. Des barres de progression apparaissent dans les listes d'issues. La syntaxe est désormais largement supportée au-delà de GitHub.

markdown
- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

Barré (GFM)

GFM ajoute le barré (~~text~~) au Markdown standard. Il fonctionne sur plusieurs lignes et se combine avec d'autres formats. Rendu en <del>. Extension GFM à l'origine, désormais dans les ajouts à la spécification CommonMark. Utile pour montrer les modifications et dépréciations.

markdown
~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

Tableaux (GFM)

Les tableaux sont une fonctionnalité GFM (pas du Markdown original). La syntaxe à pipes avec une ligne d'en-tête et un séparateur est requise. Les tableaux GFM supportent l'alignement, la mise en forme en ligne et les pipes échappées. Pour des tableaux complexes (fusion, imbrication), utilisez HTML.

markdown
| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

GitHub Alerts

Les GitHub Alerts (2023+) utilisent un marqueur [!TYPE] en première ligne d'un blockquote : NOTE, TIP, IMPORTANT, WARNING, CAUTION. Elles se rendent avec des couleurs et icônes distinctes sur GitHub. Parfaites pour les encadrés dans les README et docs. La syntaxe est spécifique à GitHub.

markdown
> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

HTML brut interdit

GFM filtre le HTML brut par sécurité — <script>, <style>, <title>, parfois <iframe>, et les gestionnaires d'événements sont retirés. Cela prévient le XSS dans le contenu généré par les utilisateurs. Le HTML sûr comme <details>, <kbd>, <sup> passe. Connaissez la allow-list de votre moteur quand vous mêlez HTML.

markdown
GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

Liens automatiques (GFM)

GFM auto-lie les URLs brutes (https://...) et les domaines www. sans chevrons. Pour la portabilité, les chevrons (<url>) fonctionnent dans tous les dialectes. L'auto-linking peut surprendre — utilisez les chevrons quand vous voulez afficher une URL littéralement avec du texte adjacent.

markdown
Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.
16

Syntaxe étendue

Surlignage

La syntaxe de surlignage ==text== est une extension (ni GFM ni CommonMark) — supportée par certains moteurs comme markdown-it avec un plugin. La balise HTML <mark> est universellement supportée. Utilisez le surlignage pour souligner des termes clés ; l'abus réduit l'impact.

markdown
==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

Indice et exposant

L'indice (~text~) et l'exposant (^text^) sont des extensions Pandoc/markdown-it, pas standards. Pour un rendu universel, utilisez HTML <sub>/<sup> ou Unicode. Utile dans le contenu scientifique et mathématique écrit en Markdown.

markdown
H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

Syntaxe d'attributs

La syntaxe d'attributs {#id .class key=val} (Pandoc, certains plugins markdown-it) attache des attributs HTML aux éléments. Utile pour les hooks de style, ancres personnalisées et cibles de liens. Peu portable — retombe en texte littéral dans les moteurs non supportés. À utiliser avec parcimonie.

markdown
## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

Conteneurs personnalisés

Les conteneurs personnalisés (:::type ... :::) sont supportés par VuePress, Docusaurus, VitePress et les outils de docs similaires. Ils se rendent en boîtes d'encadré stylées. Le type correspond à une classe CSS. Parfait pour des docs à thème mais non portable vers les moteurs Markdown simples.

markdown
:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

Maths et LaTeX (KaTeX)

Le support des maths dépend du moteur : GitHub supporte $...$ en ligne et $$...$$ en bloc (avec MathJax/KaTeX). Tous les moteurs Markdown ne supportent pas les maths. Pour une compatibilité maximale, rendez les maths en images ou utilisez MathJax directement. Utile pour les docs scientifiques et techniques.

markdown
Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.
17

Outils et éditeurs

VS Code

VS Code offre un aperçu Markdown intégré et un écosystème d'extensions riche. Markdown All in One ajoute des raccourcis (gras, TOC, aperçu). markdownlint impose le style. Preview Enhanced supporte les diagrammes, maths et exports. Configurez la césure de ligne pour un confort d'édition.

markdown
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora

Typora est un éditeur Markdown WYSIWYG populaire — il rend en ligne au fil de la frappe, supprimant le flux en deux volets. Il supporte GFM, tableaux, blocs de code, maths et Mermaid. Exporte vers de nombreux formats via ses outils intégrés. Payant mais abouti ; parfait pour les flux centrés sur l'écriture.

markdown
Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian

Obsidian stocke les notes en fichiers Markdown locaux avec des fonctions puissantes : wiki-links, backlinks, vue en graphe et tags. Il étend le Markdown avec callouts, embeds et Dataview. Idéal pour Zettelkasten et la gestion de connaissances personnelle. Gratuit pour un usage personnel.

markdown
Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

Markdown Lint

markdownlint impose un style cohérent dans les fichiers Markdown. Configurez les règles dans .markdownlint.json. Désactivations courantes : MD013 (longueur de ligne) pour la prose, MD033 (HTML en ligne) quand le HTML est nécessaire. MD040 rappelle de baliser les blocs de code d'un langage. S'intègre à la CI et aux éditeurs.

markdown
# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc

Pandoc est le « couteau suisse » de la conversion de documents — Markdown vers/depuis HTML, PDF, Word, LaTeX, EPUB, diapositives. Il supporte les extensions Markdown (citations, maths, listes de définitions, attributs bruts). Le flag -s crée des documents autonomes. Indispensable pour les flux académiques et éditoriaux.

markdown
# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

Éditeurs en ligne

Les éditeurs en ligne sont parfaits pour des modifications rapides et le partage. StackEdit et Dillinger sont des éditeurs solo complets. HackMD/HedgeDoc ajoutent la collaboration en temps réel. L'éditeur web de GitHub a un onglet Preview. Tous supportent le Markdown standard ; les fonctions GFM marchent mieux dans l'éditeur GitHub.

markdown
Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.
18

Bonnes pratiques

Lisibilité d'abord

Le principe central de Markdown est la lisibilité en texte brut. Préférez la syntaxe la plus lisible : titres #, listes -, gras **. Évitez l'imbrication excessive et le formatage superflu. Si la source brute est agréable à lire dans un éditeur de texte, vous utilisez bien Markdown.

markdown
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

Longueur de ligne et césure

Deux approches valides : le hard-wrap (une phrase par ligne) donne des diffs git propres et une édition facile ; le soft-wrap (un paragraphe par ligne) évite le travail de reflow. Choisissez-en une par projet et restez cohérent. Configurez la largeur de césure de votre éditeur (typiquement 80-120 caractères) en conséquence.

markdown
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

Cohérence

Markdown propose plusieurs syntaxes pour un même résultat (gras ** vs __, listes - vs * vs +). Choisissez une convention par projet et faites-la respecter avec markdownlint. La cohérence réduit la charge cognitive des lecteurs et contributeurs, et facilite le traitement automatisé.

markdown
# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

Bonnes pratiques des liens

Utilisez les liens par référence pour les URLs longues afin de garder la prose lisible. Utilisez les liens en ligne pour les références courtes et locales. Un texte de lien descriptif améliore l'accessibilité et le SEO — évitez « cliquez ici ». Les titres ajoutent du contexte en info-bulle. Regroupez les définitions de références en fin de section ou de document.

markdown
# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

Accessibilité

L'accessibilité compte en Markdown : texte alternatif significatif pour les images (alt vide pour les décoratives), texte de lien descriptif (pas « cliquez ici »), hiérarchie de titres correcte (ne sautez pas de niveaux), et HTML sémantique (kbd, abbr, cite) là où Markdown est limité. Les lecteurs d'écran en dépendent.

markdown
# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

Erreurs courantes

Pièges courants : lignes vides manquantes autour des éléments blocs (listes, citations, code), indentation incohérente dans les listes imbriquées, blocs de code non fermés, mélange tabulations/espaces. Prévisualisez toujours avant de publier. Lancez markdownlint pour détecter les problèmes automatiquement. Testez dans votre moteur cible.

markdown
# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.