Comment faire un tableau en Markdown :syntaxe, alignement et cellules multilignes.

La syntaxe de base d’un tableau Markdown

Les tableaux font partie de GitHub Flavored Markdown (GFM), la variante utilisée par GitHub, GitLab et la plupart des applications Markdown. Un tableau demande trois éléments :

1. Une ligne d’en-tête

   Les noms des colonnes, séparés par des barres verticales : | Name | Role |.

2. Une ligne de séparation

   Une ligne de tirets, un groupe par colonne, juste sous l’en-tête : | --- | --- |. Elle doit avoir autant de cellules que l’en-tête, sinon le texte reste du texte brut et aucun tableau n’apparaît.

3. Les rangées

   Une ligne par rangée, cellules séparées par des barres verticales. Une rangée avec trop peu de cellules est complétée par des cellules vides ; les cellules en trop sont ignorées. Le tableau se termine à la première ligne vide.

| Name  | Role     |
| ----- | -------- |
| Alice | Designer |
| Bob   | Engineer |

Voici ce que voit le lecteur :

Les barres verticales au début et à la fin de chaque ligne sont facultatives, mais rendent le tableau plus lisible. Les colonnes n’ont pas besoin d’être alignées dans le source ; le remplissage ci-dessus ne sert qu’aux humains. Les cellules peuvent contenir du gras, de l’italique, du code, des liens et des images.

Alignement dans un tableau Markdown

Placez un deux-points à gauche, à droite ou aux deux extrémités des tirets d’une colonne :

| Item   | Qty | Price |
|:-------|:---:|------:|
| Pencil |  12 |  $1.50 |
| Ruler  |   3 |  $4.00 |

L’alignement s’applique à toute la colonne, en-tête compris. Il se règle une fois dans la ligne de séparation, pas cellule par cellule. Alignez les nombres à droite pour que les chiffres tombent les uns sous les autres.

Une barre verticale ou une deuxième ligne dans une cellule

Une barre verticale termine une cellule : celle qui fait partie du texte doit donc être précédée d’une barre oblique inverse. GFM l’exige même dans du code en ligne :

| Command            | Meaning          |
|--------------------|------------------|
| `a \| b`           | a pipe, in code  |
| Either \| or       | a pipe, in text  |

Un tableau à barres verticales a une ligne par rangée : une cellule ne peut donc pas contenir de vrai saut de ligne ni de second paragraphe. Le contournement habituel est la balise HTML <br> :

| Step  | What to do                          |
|-------|-------------------------------------|
| Build | Run the build.<br>Fix any errors.  |
| Ship  | Tag the release.<br>Push the tag.  |

La même astuce donne une cellule multiligne sur GitHub et dans la plupart des applications qui acceptent le HTML. Une liste Markdown ne fonctionne pas dans une cellule ; si une cellule a besoin d’une liste, écrivez <br> entre de courts éléments ou sortez la liste du tableau.

Tableaux larges et textes longs

Markdown n’a ni réglage de largeur de colonne ni fusion de cellules ; c’est l’application qui affiche le tableau qui décide comment il s’adapte. Quelques habitudes gardent un tableau lisible partout :

• Gardez les cellules courtes, un mot ou un nombre. Mettez la longue explication dans une phrase sous le tableau.
• Utilisez moins de colonnes. Si un tableau en a huit, retournez-le : les colonnes deviennent les éléments et les lignes les propriétés.
• N’alignez pas le source avec des espaces dans un tableau que vous modifiez souvent ; une cellule changée obligerait à réajuster chaque ligne.
• Pour des cellules fusionnées, des rangées étendues ou une légende, écrivez le tableau en HTML. La plupart des applications Markdown affichent un simple <table>.

Pourquoi un tableau Markdown ne s’affiche pas

• Pas de ligne de séparation. C’est la ligne de tirets qui fait du texte un tableau.
• Le nombre de cellules diffère. Si l’en-tête a trois cellules et la ligne de séparation deux, rien ne s’affiche.
• Une barre verticale non échappée dans une cellule la coupe en deux. Écrivez \|.
• Une ligne vide dans le tableau. Le tableau se termine là ; le reste est du texte brut.
• L’application ne gère pas les tableaux. Les tableaux ne figurent ni dans le Markdown d’origine ni dans le noyau de CommonMark. Ils viennent de GFM, si bien qu’un analyseur minimal affiche les barres verticales comme du texte.

Pour voir le résultat avant de valider, ouvrez le fichier dans un lecteur Markdown. DotMD affiche les tableaux mis en forme, et la lecture est gratuite. Dans DotMD Editor, Insert → Table place dans votre fichier un tableau de trois colonnes prêt à l’emploi, et l’aperçu en direct le redessine pendant que vous tapez.

Questions sur les tableaux Markdown

Plus de questions