Guide de syntaxe Markdown — Titres, tableaux, code et plus

Voici la référence de syntaxe Markdown que vous pouvez mettre en signet et consulter ultérieurement. Chaque élément est couvert avec un exemple réel — titres, emphase, liens, images, listes, blocs de code, tableaux, citations et plus encore. Lorsqu'une fonctionnalité fait partie du standard CommonMark, elle est marquée comme telle ; les extensions de GitHub Flavored Markdown (GFM) sont explicitement signalées afin que vous sachiez ce qui est universellement pris en charge et ce qui dépend du rendu.

Titres

Markdown a deux styles de titres. Le style ATX utilise des caractères dièse — un # pour h1 jusqu'à six ###### pour h6. Le style setext utilise des soulignements de caractères = ou - et n'atteint que h1 et h2. ATX est le style que vous devriez utiliser partout — il est explicite, il s'étend à tous les six niveaux, et c'est ce que chaque outil prend en charge. Une erreur courante : oublier l'espace après le #. En termes stricts, #Titre n'est pas un titre dans CommonMark — l'espace est requis.

# Page Title (h1)
## Section Heading (h2)
### Subsection (h3)
#### Detail Level (h4)
##### Minor Heading (h5)
###### Smallest Heading (h6)

---

<!-- Setext style — only h1 and h2, rarely used -->
Page Title
==========

Section Heading
---------------

Dans un document réel, vous utilisez typiquement un h1 en haut (le titre du document), h2 pour les sections principales, et h3 pour les sous-sections dans celles-ci. Aller plus loin que h3 est un signe que votre document pourrait nécessiter une restructuration plutôt qu'un autre niveau d'imbrication.

Mise en forme du texte

Le gras utilise des doubles astérisques ou des doubles soulignements. L'italique utilise des astérisques simples ou des soulignements simples. Gras-italique combine trois de l'un ou de l'autre. Le texte barré est une extension GFM et utilise des doubles tildes. Le code en ligne utilise des backticks.

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough~~ (GFM only)
`inline code`

Les variantes * et _ sont généralement interchangeables, mais elles diffèrent dans un cas particulier : l'emphase au milieu d'un mot. Les astérisques fonctionnent au milieu d'un mot (in*croyable*ment se rend comme incroyablement), mais les soulignements ne le font pas — in_croyable_ment se rend littéralement dans CommonMark car les soulignements dans les mots sont traités comme des caractères de mot, pas comme des marqueurs d'emphase. Cela compte dans l'écriture technique où les soulignements apparaissent dans les identifiants. En règle générale : utilisez * pour l'emphase et réservez _ uniquement si vous avez une forte préférence de style. Ne mélangez pas * et _ dans le même span d'emphase — *texte_ ne se fermera pas correctement.

Liens et images

Il existe trois styles de liens : les liens en ligne, les liens de référence et les liens automatiques. Les images suivent la même syntaxe que les liens en ligne mais avec un préfixe !.

<!-- Inline link: [text](url) or [text](url "title") -->
Read the [CommonMark spec](https://spec.commonmark.org/current/ "CommonMark Specification")
Format Markdown with the [Markdown Formatter](/markdown-formatter)

<!-- Reference link: define the URL separately — cleaner in long documents -->
Check the [GFM spec][gfm] for GitHub-specific extensions.

[gfm]: https://github.github.com/gfm/

<!-- Autolink: angle brackets make a URL or email clickable -->
<https://commonmark.org>
<[email protected]>

<!-- Image: same as inline link but with ! prefix -->
![Project screenshot](./docs/screenshot.png "Dashboard view")
![Alt text for accessibility](https://example.com/logo.png)

Listes

Les listes non ordonnées utilisent -, * ou + comme marqueurs de puce. Les listes ordonnées utilisent des chiffres suivis d'un point. Imbriquez les listes en indentant de deux ou quatre espaces. Les listes de tâches (GFM) utilisent [ ] pour non coché et [x] pour coché.

<!-- Unordered list -->
- Install dependencies
- Configure environment variables
- Run the dev server

<!-- Ordered list -->
1. Clone the repository
2. Run `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run `npm run dev`

<!-- Nested list (indent 2 or 4 spaces) -->
- Backend
  - Set up PostgreSQL
  - Configure connection string
- Frontend
  - Install Tailwind
  - Configure PostCSS

<!-- Task list (GFM) — great for README checklists -->
## Release Checklist

- [x] Unit tests passing
- [x] End-to-end tests passing
- [ ] Changelog updated
- [ ] Docker image tagged
- [ ] Deployment approved

Code — En ligne et délimité

Le code en ligne utilise un seul backtick de chaque côté. Pour les blocs, utilisez des triples backticks (blocs de code délimités) et spécifiez optionnellement l'identifiant de langage juste après la clôture d'ouverture — cela active la coloration syntaxique dans GitHub, les aperçus VS Code et la plupart des générateurs de sites statiques. Vous pouvez également utiliser des blocs de code indentés (4 espaces d'indentation), mais préférez les blocs délimités : ils prennent en charge les indices de langage, ils sont explicites, et ils fonctionnent même quand le contenu environnant a également une indentation.

<!-- Inline code -->
Use the `fetch()` API to make HTTP requests.
Set the `Content-Type` header to `application/json`.

<!-- Fenced code block with language hint -->
```python
import json

with open("config.json") as f:
    config = json.load(f)

print(config["database"]["host"])
```

```typescript
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}
```

```bash
# Install dependencies and start the dev server
npm install
npm run dev
```

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  }
}
```

```yaml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
```

Identifiants de langage courants : python, js ou javascript, ts ou typescript, bash ou sh, json, yaml, html, css, sql, go, rust, java. Prévisualisez comment votre Markdown se rend avec l'outil Aperçu Markdown.

Tableaux (GFM)

Les tableaux sont une extension GitHub Flavored Markdown — ils ne font pas partie du standard CommonMark. Ils fonctionnent dans GitHub, GitLab, la plupart des générateurs de sites statiques et VS Code, mais pas dans tous les processeurs Markdown. La syntaxe utilise des caractères pipe pour séparer les colonnes et une ligne séparatrice de tirets pour marquer l'en-tête. Les deux-points dans la ligne séparatrice contrôlent l'alignement des colonnes.

| Feature              | CommonMark | GFM       |
| -------------------- | :--------: | :-------: |
| Headings             | ✅         | ✅        |
| Bold / Italic        | ✅         | ✅        |
| Fenced code blocks   | ✅         | ✅        |
| Tables               | ❌         | ✅        |
| Task lists           | ❌         | ✅        |
| Strikethrough        | ❌         | ✅        |
| Autolinks            | ✅         | ✅ (ext.) |

L'alignement des colonnes est défini dans la ligne séparatrice. :--- aligne à gauche (par défaut). ---: aligne à droite. :---: centre. Vous n'avez pas besoin de rembourrer les colonnes avec des espaces pour les aligner visuellement dans la source — c'est cosmétique et n'a aucun effet sur la sortie rendue. Les pipes au début et à la fin de chaque ligne sont techniquement optionnels dans GFM mais les inclure est le style le plus clair.

Citations

Les citations préfixent chaque ligne par >. Les citations imbriquées utilisent >>. Vous pouvez inclure d'autres éléments Markdown — titres, listes, blocs de code — dans une citation, ce qui les rend utiles pour les boîtes d'alerte dans la documentation.

> **Note:** As of Node.js 18, the `fetch` API is available globally
> without importing anything. No more `node-fetch` dependency.

> This is a quote that spans
> multiple lines.
>
> And has a second paragraph.

> Outer quote.
>
> > Nested quote — useful for "quoting a quote" in changelogs
> > or spec discussions.

<!-- Blockquote containing a code block — useful for quoting error messages -->
> The migration failed with:
>
> ```
> ERROR: relation "users" already exists
> ```

Règles horizontales, sauts de ligne et échappement

Ces trois fonctionnalités posent problème aux gens car leur comportement ressemble à un bogue jusqu'à ce que vous connaissiez les règles. Les règles horizontales, les sauts de ligne durs et l'échappement par barre oblique inverse ont tous une syntaxe spécifique qui n'est pas évidente.

<!-- Horizontal rules: three or more of ---, ***, or ___ on their own line -->
---
***
___

<!-- All three render as <hr>. Most common style is --- -->

<!-- Hard line breaks: end a line with two trailing spaces, or use backslash -->
First line with two trailing spaces
Second line (rendered as a new line, not a new paragraph)

First line with backslash\
Second line (same result)

<!-- A single newline in Markdown source is NOT a line break — it's a space.
     Two newlines = a paragraph break. -->

<!-- Backslash escaping: put  before any Markdown character to render it literally -->
*This is not italic*
# This is not a heading
[Not a link](not-a-url)
`Not inline code`

<!-- Characters that can be escaped -->
\ ` * _ { } [ ] ( ) # + - . !

HTML dans Markdown

La plupart des processeurs Markdown transmettent le HTML brut sans modification, ce qui déverrouille quelques patterns utiles que la syntaxe Markdown pure ne peut pas exprimer. Le cas d'utilisation le plus courant dans les READMEs GitHub est la section pliable <details>/<summary>. D'autres utiles : <kbd> pour les raccourcis clavier, et les attributs id personnalisés sur les titres pour des liens d'ancre précis.

<!-- Collapsible section — very common in GitHub READMEs -->
<details>
<summary>Click to expand: Advanced configuration options</summary>

You can override the defaults by creating a `config.local.json` file
in the project root. Supported keys:

| Key        | Default | Description             |
| ---------- | ------- | ----------------------- |
| `port`     | 3000    | Dev server port         |
| `logLevel` | `info`  | One of debug/info/warn  |

</details>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette.

<!-- Custom heading ID for anchor links -->
<h2 id="configuration-reference">Configuration Reference</h2>

<!-- Link to that heading from anywhere -->
See the [Configuration Reference](#configuration-reference).

Une mise en garde importante : le bloc <details> nécessite une ligne vide entre la balise de fermeture </summary> et le contenu du corps si ce contenu contient du Markdown. Sans la ligne vide, le Markdown à l'intérieur ne sera pas analysé — il s'affichera comme du texte brut. Vous pouvez nettoyer et formater vos fichiers Markdown avec l'outil Formateur Markdown.

Conclusion

Cela couvre la syntaxe complète — CommonMark standard et les extensions GFM que les développeurs utilisent quotidiennement. Pour le mot définitif sur les cas limites, la spécification CommonMark et la spécification GFM sont toutes deux des documents lisibles, pas seulement des dumps de référence. La référence rapide CommonMark est un résumé pratique sur une seule page. Les pages syntaxe de base Markdown Guide et syntaxe étendue sont également bien organisées si vous voulez plus d'explication en prose à côté des exemples. Quand vous devez voir exactement à quoi ressemblera votre Markdown avant de le committer, l'outil Aperçu Markdown le rend en direct dans votre navigateur. Pour nettoyer le formatage incohérent dans un document, le Formateur Markdown normalise les styles de titres, les marqueurs de liste et l'espacement. Et pour produire du HTML propre à partir de la sortie Markdown, le Formateur HTML embellit ce que le processeur Markdown émet.