Tableaux Markdown : les créer

La syntaxe de base

Un tableau Markdown commence par une ligne d'en-tête, puis une ligne de séparation de tirets, puis des lignes de données. Les colonnes sont séparées par des barres verticales.

La ligne de séparation est ce qui transforme trois lignes en tableau. Chaque colonne y demande au moins un tiret, et rien d'autre que des deux-points facultatifs. Sans elle, les lignes s'affichent comme de simples paragraphes : la cause la plus fréquente d'un tableau qui « ne marche pas ».

Les tableaux sont une extension GitHub Flavored Markdown (GFM) ; le moteur doit donc les prendre en charge, et c'est le cas de la plupart des moteurs modernes. Inutile non plus d'aligner les barres dans le source : `|Outil|Type|` et `| Outil | Type |` rendent à l'identique.

| Outil | Type |
| --- | --- |
| SHA-256 | Hachage |
| AES-GCM | Chiffrement |

Contrôler l'alignement

Ajoutez des deux-points dans la ligne de séparation pour aligner les colonnes : :--- gauche, :---: centre, ---: droite.

Le deux-points fait le travail ; les tirets autour ne sont que du remplissage. L'alignement à gauche est le défaut, donc `---` et `:---` donnent le même résultat chez la plupart des moteurs.

L'alignement est une indication d'affichage, pas une propriété des données. Des nombres alignés à droite se retrouvent sur la virgule décimale, ce qui facilite la comparaison. Tous les moteurs ne le respectent pas, cependant : certains minimalistes alignent tout à gauche ; vérifiez la cible.

| Gauche | Centre | Droite |
| :--- | :---: | ---: |
| 1 | 2 | 3 |
| 10 | 20 | 30 |

Échapper les barres verticales et le contenu spécial

Pour inclure une barre verticale littérale dans une cellule, échappez-la avec une barre oblique inversée : \|. Les segments de code et les liens fonctionnent normalement dans les cellules.

L'échappement par barre oblique inversée est traité avant le découpage de la cellule : \| fonctionne donc aussi dans le code en ligne et le gras. Un pipeline shell comme `ps \| grep node` reste dans une seule cellule.

Liens, emphase et code en ligne sont analysés normalement dans les cellules. Ce qu'on ne peut pas faire, c'est imbriquer du contenu de bloc — pas de listes, titres ni blocs de code dans une cellule ; placez-les hors du tableau.

• Échappez les barres : \| dans une cellule
• Utilisez les accents graves pour le code en ligne : `npx tsx`
• Les liens fonctionnent dans les cellules : docs
• Gardez les cellules courtes ; le texte long va dans une liste ou une section
• Une barre échappée par une barre oblique inversée fonctionne aussi dans les accents graves et le gras

Tableaux vs listes

Un tableau se justifie quand chaque ligne répond à la même question avec une valeur différente : liste de paramètres, comparaison d'algorithmes, journal de modifications à colonnes fixes. Dès que les lignes ressemblent à des phrases, une liste est probablement plus adaptée.

Pensez au lecteur sur mobile. Un tableau à quatre colonnes avec une longue colonne d'URL devient un défilement horizontal, et beaucoup de lecteurs ne défilent pas — scindez le tableau ou réduisez le contenu large à du texte de lien.

Ma règle simple : quand je documente un outil CLI, je limite les tableaux à trois colonnes et je place les exemples longs dans un bloc de code sous le tableau.

• Utilisez les tableaux pour les comparaisons, paramètres et données structurées
• Utilisez les listes pour les séquences, options et contenus riches en prose
• Limitez les tableaux à 3-5 colonnes sur mobile pour éviter le défilement horizontal
• Si un tableau a besoin de contenu imbriqué, scindez-le en tableaux plus petits ou en prose
• Utilisez une liste quand l'ordre compte et que chaque élément se suffit à lui-même
• Gardez les en-têtes courts pour que les lecteurs d'écran les annoncent proprement

Prévisualiser et affiner localement

L'aperçu Markdown rend localement dans votre navigateur : un bon endroit pour expérimenter les deux-points et l'échappement. Gardez le source d'un côté de l'écran et l'aperçu de l'autre.

1. Écrivez votre tableau en Markdown.
2. Ouvrez l'aperçu Markdown dans votre navigateur.
3. Collez la source et vérifiez l'alignement rendu.
4. Ajustez les deux-points et l'échappement jusqu'à ce que le tableau soit propre, puis exportez ou copiez.
5. Vérifiez une dernière fois le source brut : une barre oubliée ou une ligne de séparation manquante est le coupable habituel.
6. Testez le même source là où la documentation vivra — GitHub, GitLab ou votre CMS — car les moteurs diffèrent.

FAQ

Références

• Spécification GitHub Flavored Markdown – Tableaux : https://github.github.com/gfm/#tables-extension-
• Spécification CommonMark : https://spec.commonmark.org/
• RFC 7763 – The text/markdown Media Type : https://www.rfc-editor.org/info/rfc7763/
• RFC 7764 – Guidance on Markdown : https://www.rfc-editor.org/info/rfc7764/
• Syntaxe Markdown d'origine (John Gruber) : https://daringfireball.net/projects/markdown/syntax
• MDN – How to write in Markdown : https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN