Les tableaux Markdown semblent intimidants en texte brut. Des barres verticales partout, des tirets qui s'alignent (ou pas), du contenu qui refuse de rester dans sa colonne. Mais la syntaxe est en réalité simple une fois que vous avez compris ses trois parties : l'en-tête, le séparateur et les lignes.

Voici tout ce que j'ai appris sur les tableaux Markdown, des bases jusqu'aux cas particuliers.

La syntaxe de base

Un tableau Markdown comporte trois composants : une ligne d'en-tête, une ligne de séparation et une ou plusieurs lignes de données.

| Nom     | Rôle      | Lieu     |
| ------- | --------- | -------- |
| Alice   | Dev       | Paris    |
| Bob     | Designer  | Lyon     |
| Charlie | PM        | Remote   |

Les règles :

Utilisez | (barre verticale ou pipe) pour séparer les colonnes.
Utilisez --- (trois tirets ou plus) dans la ligne de séparation pour définir chaque colonne.
Ajoutez une barre verticale au début et à la fin de chaque ligne. C'est techniquement facultatif dans certains outils de rendu, mais faites-le toujours pour des raisons de compatibilité.
Laissez une ligne vide avant le tableau. Sans cela, certains moteurs de rendu ne l'analyseront pas correctement.

Les largeurs des cellules n'ont pas besoin de correspondre. Ceci est parfaitement valide :

| Nom | Rôle |
| --- | --- |
| Alice | Développeuse |
| Bob | Designer |

Le rendu sera identique, que vous aligniez les barres verticales dans le fichier source ou non. L'alignement dans le fichier brut est purement cosmétique, il aide à la lisibilité lorsque vous ouvrez le fichier .md dans un éditeur de texte, rien de plus.

Alignement des colonnes

Par défaut, le texte est aligné à gauche. Vous pouvez changer cela avec des deux-points dans la ligne de séparation :

| Produit         | En stock |  Prix |
| :-------------- | :------: | ----: |
| Livre Markdown  |   Oui    | 19.99 |
| Cheat Sheet     |   Non    |  4.99 |
| Pack Stickers   |   Oui    |  2.49 |

Les deux-points fonctionnent ainsi :

:--- ou :-- aligné à gauche (par défaut).
:---: ou :-: centré.
---: ou --: aligné à droite.

Le nombre de tirets n'a pas d'importance. :--: fonctionne de la même manière que :--------:. Seule la position des deux-points compte.

Un modèle courant : alignez à gauche les colonnes de texte, centrez les colonnes de statut et alignez à droite les nombres. Cela rend les tableaux beaucoup plus faciles à lire.

Formater le texte à l'intérieur des cellules

Vous pouvez utiliser la plupart des formatages Markdown en ligne dans les cellules d'un tableau :

Gras : **texte**
Italique : *texte*
Code : `code`
Liens : [texte](url)
~~Barré~~ : ~~texte~~

Exemple :

| Fonctionnalité   | Statut        | Notes                      |
| ---------------- | ------------- | -------------------------- |
| **Mode sombre**  | `Terminé`     | Livré dans la v2.1         |
| *Synchronisation*| `En cours`    | [Voir la PR #42](https://…)|
| ~~Ancienne feat~~| `Supprimée`   | Obsolète dans la v3.0      |

& Ce que vous ne pouvez généralement pas utiliser à l'intérieur des cellules de tableau de style GitHub Flavored Markdown (GFM) en tant que syntaxe Markdown : les titres, les citations, les lignes horizontales, les listes ou les blocs de code. Les tableaux analysent le contenu en ligne, pas les éléments de bloc. Les images sont en ligne, donc de nombreux moteurs de rendu les prennent en charge, mais elles peuvent rendre les tableaux plus difficiles à lire.

Échapper le caractère pipe (barre verticale)

Puisque | est le délimiteur de colonne, afficher une vraie barre verticale à l'intérieur d'une cellule nécessite de l'échapper.

Deux méthodes :

| Syntaxe   | Exemple      |
| --------- | ------------ |
| Antislash | A \| B       |
| Code HTML | A &#124; B   |

La méthode de l'antislash (\|) fonctionne dans le GitHub Flavored Markdown (GFM) et la plupart des outils de rendu modernes. L'entité HTML (|) est la solution de secours universelle, elle fonctionne partout.

Contenu multiligne dans les cellules

Les tableaux GitHub Flavored Markdown (GFM) ne prennent pas nativement en charge les blocs Markdown multilignes au sein d'une seule cellule. En pratique, il vaut mieux traiter chaque cellule comme une ligne unique de contenu en ligne.

Mais en réalité, on a souvent besoin de plus de quelques mots dans une cellule. Voici les solutions de contournement :

Sauts de ligne HTML

La balise <br> fonctionne dans la plupart des moteurs de rendu :

| Étape | Description                                  |
| ----- | -------------------------------------------- |
| 1     | Cloner le dépôt<br>Lancer `npm install`      |
| 2     | Créer un fichier `.env`<br>Ajouter la clé API|

C'est la solution de contournement la plus courante. Elle fonctionne sur GitHub, Obsidian, GitLab, et de nombreux générateurs de sites statiques qui autorisent le HTML en ligne, mais il vaut toujours mieux la tester dans votre moteur de rendu cible.

Listes HTML dans les cellules

Si vous avez besoin de vraies puces à l'intérieur d'une cellule, utilisez le HTML :

| Module | Inclus                                                  |
| ------ | ------------------------------------------------------- |
| Base   | <ul><li>Analyseur</li><li>Moteur de rendu</li></ul>     |
| Extras | <ul><li>Coloration syntaxique</li><li>Tableaux</li></ul>|

Tous les moteurs de rendu ne le prennent pas en charge. Parce que les balises de liste comme <ul> sont du HTML de niveau bloc, la compatibilité dans les cellules de tableau varie davantage qu'avec <br>. Certains moteurs de rendu les gèrent, d'autres les suppriment, et d'autres encore les affichent de manière incohérente. Testez avant de vous engager dans cette approche.

Tableaux sans en-tête

Dans les tableaux de style GitHub Flavored Markdown (GFM), une ligne d'en-tête est obligatoire. Il n'y a pas moyen de faire autrement avec cette syntaxe.

Si vous ne voulez pas d'en-tête visible, la meilleure solution de contournement consiste à utiliser des cellules d'en-tête vides :

|     |     |
| --- | --- |
| A1  | B1  |
| A2  | B2  |

La ligne d'en-tête existe toujours dans la sortie HTML (sous la forme <thead>), mais visuellement, elle s'affiche comme une ligne vide ou est masquée selon le CSS. Sur GitHub, l'en-tête vide est visible mais discret. Dans Obsidian, cela dépend du thème.

Une autre approche consiste à utiliser directement le HTML :

<table>
  <tr><td>A1</td><td>B1</td></tr>
  <tr><td>A2</td><td>B2</td></tr>
</table>

Cela ignore complètement l'en-tête, mais vous perdez la simplicité de la syntaxe Markdown.

Peut-on fusionner des cellules ?

Non. Markdown n'a pas de syntaxe pour colspan ou rowspan.

Si vous avez vraiment besoin de cellules fusionnées, votre seule option est d'écrire le tableau en HTML :

<table>
  <tr>
    <th colspan="2">Nom Complet</th>
    <th>Rôle</th>
  </tr>
  <tr>
    <td>Alice</td>
    <td>Martin</td>
    <td>Dev</td>
  </tr>
</table>

Cela fonctionne dans tout moteur de rendu qui accepte les tableaux HTML. Mais cela va à l'encontre du but de Markdown : la lisibilité sous forme de code source. Je réserve les tableaux HTML aux cas où la mise en page nécessite vraiment une fusion, ce qui est plus rare qu'on ne le pense.

Ajouter une légende

Les tableaux Markdown standard ne prennent pas en charge les légendes. Aucune syntaxe n'existe pour cela.

Le contournement le plus simple consiste à ajouter une ligne en italique directement sous le tableau :

| Trimestre | Revenus |
| --------- | ------: |
| Q1        |   120K €|
| Q2        |   145K €|

*Tableau 1 : Revenus par trimestre, 2025.*

Pour la sortie HTML, vous pouvez utiliser la balise <caption> :

<table>
  <caption>Revenus par trimestre, 2025</caption>
  <tr><th>Trimestre</th><th>Revenus</th></tr>
  <tr><td>Q1</td><td>120K €</td></tr>
</table>

Si vous utilisez un générateur de site statique (Nuxt Content, Hugo, Astro, etc.), vérifiez s'il propose une extension ou un shortcode pour les légendes de tableaux. Certains le font.

Les tableaux sur GitHub

GitHub Flavored Markdown (GFM) prend entièrement en charge les tableaux. Quelques spécificités :

Les barres verticales au début et à la fin des lignes sont facultatives en GFM, mais je recommande de toujours les inclure.
GitHub affiche les tableaux avec un ombrage alterné des lignes (rayures zébrées), ce qui aide à la lisibilité.
Le formatage en ligne fonctionne : gras, italique, code, liens, barré.
Le HTML à l'intérieur des cellules est partiellement pris en charge. <br> fonctionne bien, mais un HTML plus complexe dans les cellules est moins prévisible et certaines balises sont supprimées.
GitHub renvoie automatiquement à la ligne le contenu long des cellules. Pas de défilement horizontal, le texte passe simplement à la ligne suivante dans la cellule.

Un modèle courant dans les issues et PR GitHub : utiliser des tableaux pour des comparaisons.

## Comparaison

| Approche | Avantages         | Inconvénients           |
| -------- | ----------------- | ----------------------- |
| Option A | Simple, rapide    | Fonctionnalités limitées|
| Option B | Riche en options  | Configuration complexe  |

Les tableaux dans Fude

Dans Fude, les tableaux Markdown standard fonctionnent comme vous vous y attendez. Si votre tableau utilise la syntaxe habituelle de style GitHub, il devrait s'afficher proprement :

une ligne d'en-tête, une ligne de séparation et des lignes de corps
l'alignement des colonnes avec :---, :---: et ---:
le formatage en ligne dans les cellules comme le gras, l'italique, le code et les liens
Les liens dans les tableaux se comportent comme les liens ailleurs dans Fude. Les liens web s'ouvrent normalement, et les liens Markdown peuvent toujours pointer vers d'autres notes.
<br> à l'intérieur d'une cellule fonctionne, il ajoute un saut de ligne

Si vous vous en tenez à la syntaxe standard des tableaux Markdown, Fude la gérera très bien.

Les listes HTML comme <ul><li>...</li></ul> à l'intérieur des cellules ne sont pas prises en charge
les tableaux HTML bruts avec <table>, <caption>, colspan ou rowspan non plus

Les tableaux dans Obsidian

Obsidian prend en charge la syntaxe standard des tableaux Markdown. En pratique :

Le mode Aperçu en direct (Live Preview) affiche les tableaux en temps réel pendant que vous tapez.
Obsidian dispose d'un éditeur de tableau intégré (clic droit sur un tableau) qui vous permet d'ajouter/supprimer des lignes et des colonnes sans toucher à la syntaxe brute.
L'alignement avec : fonctionne comme prévu.
<br> dans les cellules fonctionne en mode lecture et en mode aperçu en direct.

Une chose à surveiller : si votre tableau se trouve dans un bloc d'appel (callout) (> [!note]), chaque ligne doit être préfixée par >. Cela devient fastidieux pour les grands tableaux.

Quand un tableau n'est pas le bon outil

Les tableaux Markdown fonctionnent bien pour les données structurées sous forme tabulaire avec un nombre constant de colonnes. Ils ne fonctionnent pas bien lorsque :

Les cellules contiennent des paragraphes de texte. Le Markdown brut devient illisible et le rendu a l'air à l'étroit.
Vous avez besoin de cellules fusionnées, de tableaux imbriqués ou de mises en page complexes. Utilisez plutôt le HTML.
Les données sont une simple liste de paires clé-valeur. Une liste de définitions ou même du texte en gras est plus simple :

**Nom :** Alice
**Rôle :** Développeuse
**Lieu :** Paris

C'est plus facile à lire (et à écrire) qu'un tableau à deux colonnes pour la même information.

Débogage des problèmes courants

"Mon tableau ne s'affiche pas"

La cause la plus fréquente : aucune ligne vide avant le tableau. Ajoutez-en une.

Deuxième cause la plus fréquente : la ligne de séparation est manquante ou mal formée. Chaque tableau a besoin d'une ligne | --- | --- | entre les lignes d'en-tête et de données. Si vous l'oubliez, l'analyseur verra du texte brut, pas un tableau.

"Les colonnes sont mal alignées dans le rendu"

Si une cellule contient plus de contenu que les autres, certains moteurs de rendu étireront cette colonne. C'est un comportement normal, les tableaux Markdown s'adaptent à la largeur du contenu. Vous ne pouvez pas définir de largeurs de colonnes fixes en Markdown.

"Mon caractère barre verticale s'affiche comme un séparateur de colonne"

Échappez-le : \| ou |. Voir la section ci-dessus sur l'échappement.

"Les sauts de ligne dans les cellules ne fonctionnent pas"

Le Markdown standard ne prend pas cela en charge. Utilisez <br> pour les sauts de ligne dans les cellules. Si <br> ne fonctionne pas, votre moteur de rendu supprime probablement les balises HTML, vérifiez sa documentation.

Référence rapide

# Tableau de base
| En-tête 1 | En-tête 2 |
| --------- | --------- |
| Cellule 1 | Cellule 2 |


# Alignement
| Gauche | Centre | Droite |
| :----- | :----: | -----: |
| A      |   B    |      C |


# Formatage
| Fonctionnalité| Statut   |
| ------------- | -------- |
| **Gras** | `code`   |
| *Italique* | [Lien]() |


# Échapper le pipe
| A \| B | C &#124; D |


# Saut de ligne dans une cellule
| Étape | Faites ceci<br>Puis cela |

Les tableaux Markdown couvrent 90 % des données structurées dont vous aurez besoin dans un fichier .md. Pour les 10 % restants (cellules fusionnées, légendes, mises en page complexes), le HTML est là pour ça.

La clé est de savoir quand utiliser l'un ou l'autre.

Pour savoir comment séparer proprement des sections autour de vos tableaux, lisez notre article : Comment ajouter une ligne horizontale en Markdown.

Si vous cherchez un visualiseur Markdown qui affiche proprement les tableaux sur tous vos appareils, avec une coloration syntaxique et une expérience de lecture soignée, jetez un œil à Fude.

📌 Télécharger Fude

Tableau Markdown : Guide complet avec exemples