Tableaux dans le Markdown : syntaxe GFM, alignement et limites
« Tables GFM avec barres verticales, alignement et limites de cellules. »
Un tableau Markdown se compose d’une ligne d’en-tête, d’une ligne de séparation composée de tirets et des lignes de données situées en dessous. C’est la ligne de séparation qui transforme les barres verticales en tableau dans le GFM et dans Hugo.
Ce guide fait partie de la section Outils de documentation en 2026 : Markdown, LaTeX, PDF et flux de travail d’impression. Les autres types de blocs se trouvent dans l’Aide-mémoire Markdown.
Les tableaux ne font pas partie de la syntaxe Markdown d’origine ni de CommonMark. Il s’agit de l’extension des tableaux dans la spécification GitHub Flavored Markdown. Hugo 0.164 utilise Goldmark avec cette extension activée par défaut (markup.goldmark.extensions.table). Les exemples ci-dessous sont encadrés pour que les barres verticales restent littérales, ce qui est le modèle décrit dans Les blocs de code Markdown.
Syntaxe des tableaux à barres verticales
Un tableau se compose de trois parties : une ligne d’en-tête, une ligne de séparation et zéro ou plusieurs lignes de données. Les cellules sont séparées par |. Une barre verticale au début et à la fin d’une ligne est facultative. Les espaces situés à côté d’une barre verticale sont supprimés.
| Header 1 | Header 2 |
| --- | --- |
| Cell A1 | Cell B1 |
| Cell A2 | Cell B2 |
Les documents d’écriture de GitHub indiquent que chaque cellule de séparation doit contenir au moins trois tirets, et qu’une ligne vide avant le tableau est requise pour que GitHub l’affiche correctement. La spécification GFM décrit la cellule de séparation comme des tirets, avec un deux-points facultatif de chaque côté, et ses exemples incluent une cellule avec un seul tiret. Hugo 0.164 a affiché ceci comme un tableau :
| A | B |
| - | - |
| 1 | 2 |
Le même rendu Hugo a également transformé un tableau en <table> lorsque la ligne précédente était un paragraphe et qu’il n’y avait pas de ligne vide. Sur GitHub, suivez le séparateur à trois tirets et la ligne vide. Sur ce site, un seul tiret suffit et la ligne vide n’est pas requise.
|Too|Tight| avec un séparateur |---|---| a également été affiché. Les espaces à côté des barres verticales sont supprimés. Les espaces dans le premier exemple permettent de garder un diff de source lisible.
La ligne d’en-tête et la ligne de séparation doivent avoir le même nombre de cellules. Si elles diffèrent, Hugo ne reconnaît pas le tableau. Cela reste du texte ordinaire, et les tirets sont alors éligibles au typographe de Hugo :
| abc | def |
| --- |
| bar |
Une ligne de données peut être plus courte ou plus longue que l’en-tête. Une ligne courte est remplie avec des cellules vides. Les cellules dépassant le nombre de l’en-tête sont supprimées.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
Le premier de ces exemples affiche une troisième cellule vide. Le second n’affiche que 1 et 2.
Une ligne sans barres verticales est toujours à l’intérieur du tableau jusqu’à une ligne vide. Hugo 0.164 a mis un bar suivant dans le tableau comme une ligne avec une deuxième cellule vide, correspondant à l’exemple 202 de GFM. Le paragraphe suivant commence après la ligne vide.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Alignement des colonnes
L’alignement est un deux-points dans la ligne de séparation. --- sans deux-points est un alignement à gauche, identique à :---.
| Left | Right | Center |
| :--- | ----: | :----: |
| text | 12.50 | yes |
| Gauche | Droite | Centre |
|---|---|---|
| texte | 12,50 | oui |
Les deux-points dans la ligne d’en-tête sont des caractères dans cette cellule. Ils ne définissent pas l’alignement. La ligne de séparation ci-dessous est celle utilisée par Hugo :
| :--- Left | Right ---: |
| :-------- | ---------- |
| Correct | Alignment |
Contenu des cellules
Les éléments en ligne fonctionnent à l’intérieur d’une cellule : mise en emphase, plages de code et liens. Les éléments de bloc ne fonctionnent pas. La spécification GFM indique que les éléments de niveau bloc ne peuvent pas être insérés dans un tableau, donc une liste ou un bloc encadré à l’intérieur d’une cellule n’est ni une liste ni un encadré.
| Feature | Status | Documentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Released* | [Docs](/api) |
| `Auth` | Beta | Coming soon |
Une barre verticale littérale est \| ou |. Hugo 0.164 a affiché les deux comme |.
| Expression | Result |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Un retour à la ligne à l’intérieur d’une cellule est une balise HTML <br>. Ce site définit markup.goldmark.renderer.unsafe sur vrai, de sorte que cette balise est conservée. Un processeur qui supprime le HTML brut concatène les deux moitiés.
Trois tirets écrits comme texte de cellule sont un autre piège dans Hugo. Le typographe réécrit --- dans une cellule en un tiret long (—). Une plage de code conserve les tirets. \--- a été affiché comme -–.
| As text | As code |
| ------- | ------- |
| --- | `---` |
Cellules fusionnées
GFM n’a pas de rowspan ou de colspan. Lorsqu’une cellule doit couvrir deux lignes, le tableau doit être en HTML. Le rendu non sécurisé de ce site laisse ce HTML dans la page :
<table>
<tr>
<td rowspan="2">Merged</td>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
</tr>
</table>
L’écriture markdown+pipe_tables de Pandoc émet la syntaxe des barres verticales sur cette page. C’est l’écriture utilisée lors de la conversion des documents Word en Markdown. Les tables en grille et d’autres mises en page spécifiques à Pandoc sont des fonctionnalités du dialecte, couvertes dans GFM vs CommonMark vs Pandoc Markdown.
Un large tableau à barres verticales défile ou déborde. Les réductions portables sont une mise en page transposée, plusieurs tableaux plus petits, ou un tableau HTML avec son propre CSS. La syntaxe des barres verticales n’a pas de légende. La table des matières de Hugo est construite à partir des en-têtes.
Vérifications lorsqu’un tableau reste du texte
Comptez les cellules dans la ligne d’en-tête et la ligne de séparation. Si ces deux compteurs diffèrent, le bloc est un paragraphe. Une ligne de données courte est toujours un tableau, avec une cellule vide à la fin. La règle MD056 de markdownlint demande à chaque ligne de correspondre à ce compte, car une ligne courte ressemble à une cellule manquante et une cellule supplémentaire est jetée.
Regardez la ligne de séparation pour les deux-points. Un deux-points situé dans l’en-tête est du texte, et la colonne reste à l’alignement du séparateur.
Si --- dans une cellule apparaît comme un seul glyphe de tiret sur ce site, c’est que le typographe l’a réécrit. Mettez les tirets dans une plage de code.
Si GitHub affiche les barres verticales comme du texte, ajoutez la ligne vide exigée par les documents de GitHub et utilisez au moins trois tirets dans chaque cellule de séparation. Hugo 0.164 acceptait déjà la forme plus courte.
Une ligne de séparation manquante est l’autre manière dont un bloc de barres verticales reste du texte. Hugo 0.164 a laissé ceci comme un paragraphe :
| Header 1 | Header 2 |
| Cell A | Cell B |
Un tableau de paramètres
La même ligne de séparation porte l’alignement et laisse de la place pour le code en ligne :
| Parameter | Type | Default | Required |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Yes |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
