Dans cet article
Que sont les tableaux Markdown ?
Les tableaux Markdown utilisent des barres verticales (|) et des traits d'union (-) pour créer des données tabulaires structurées dans des documents en texte brut. Ils font partie de GitHub Flavored Markdown (GFM) et sont pris en charge par la plupart des rendus Markdown, notamment GitHub, GitLab, VS Code et les générateurs de sites statiques.
Les tableaux Markdown sont conçus pour une présentation simple des données — en-têtes de colonnes, ligne de séparation et lignes de données. Ils sont rendus sous forme de tableaux HTML dans la sortie, ce qui les rend idéaux pour la documentation, les fichiers README et la rédaction technique sans aucune connaissance HTML.
Syntaxe des tableaux Markdown
Un tableau Markdown se compose de trois parties : la ligne d'en-tête, la ligne de séparation et une ou plusieurs lignes de données.
- Ligne d'en-tête — la première ligne définit les noms des colonnes, séparés par des barres verticales (|). Les barres initiales et finales sont optionnelles mais recommandées pour la clarté.
- Ligne de séparation — la deuxième ligne utilise des traits d'union (---) entre les barres pour séparer l'en-tête des données. Au moins trois traits d'union par colonne sont requis.
- Lignes de données — chaque ligne suivante contient des valeurs de cellules séparées par des barres. Les cellules n'ont pas besoin d'être alignées visuellement, bien que les colonnes alignées améliorent la lisibilité du source.
- Échappement des barres — si le contenu d'une cellule contient une barre verticale littérale, échappez-la avec une barre oblique inverse (\|) pour éviter qu'elle soit interprétée comme un séparateur de colonne.
Options d'alignement des colonnes
L'alignement des colonnes est contrôlé en ajoutant des deux-points à la ligne de séparation. Cela détermine comment le texte est aligné dans chaque colonne.
- Alignement à gauche (par défaut) — utilisez :--- ou --- dans le séparateur. Le texte s'aligne sur le bord gauche de la colonne. C'est la valeur par défaut quand aucun deux-points n'est spécifié.
- Alignement centré — utilisez :---: dans le séparateur. Le texte est centré dans la colonne. Utile pour les étiquettes de statut, les catégories ou les valeurs courtes.
- Alignement à droite — utilisez ---: dans le séparateur. Le texte s'aligne sur le bord droit. Idéal pour les valeurs numériques, les prix, les comptages et les mesures.
Essayez gratuitement — sans inscription
Generer des tables Markdown →Cas d'utilisation courants
Les tableaux Markdown sont utilisés partout où des données structurées doivent être présentées dans la documentation.
- Documentation README — tableaux de comparaison des fonctionnalités du projet, exigences d'installation, plateformes prises en charge et matrices de compatibilité des versions
- Documentation API — références des points d'accès avec méthode, chemin, description et tableaux de paramètres pour chaque route
- Tableaux de comparaison — comparaisons de fonctionnalités côte à côte, niveaux de tarification et évaluations d'outils dans les articles de blog et les revues techniques
- Journaux des modifications — tableaux d'historique des versions avec date, numéro de version et description des changements pour chaque version
Conseils et bonnes pratiques
Le respect de ces directives permet de garder vos tableaux Markdown lisibles aussi bien dans le source que dans la forme rendue.
- Gardez les colonnes alignées dans le source — remplissez les cellules avec des espaces pour que les colonnes s'alignent visuellement. La plupart des éditeurs et notre générateur gèrent cela automatiquement. Un source aligné est beaucoup plus facile à revoir dans les pull requests.
- Évitez le contenu complexe dans les cellules — les tableaux Markdown ne supportent pas le contenu multi-ligne, les éléments de bloc ou les tableaux imbriqués. Gardez le contenu des cellules court et simple. Pour les données complexes, envisagez d'utiliser des tableaux HTML à la place.
- Limitez le nombre de colonnes — les tableaux avec plus de 5-6 colonnes deviennent difficiles à lire sur les petits écrans. Envisagez de diviser les grands tableaux en plusieurs tableaux ciblés ou d'utiliser un format différent pour les données très larges.
Foire aux questions
Y a-t-il une limite au contenu des cellules dans les tableaux Markdown ?
Il n'y a pas de limite technique de caractères pour le contenu des cellules, mais les cellules de tableaux Markdown ne sont que sur une seule ligne. Vous ne pouvez pas inclure de sauts de ligne, de paragraphes ou d'éléments de niveau bloc comme des listes dans une cellule. Pour les contenus de cellule complexes, utilisez des tableaux HTML avec des éléments <td> qui prennent en charge tout contenu HTML.
Puis-je fusionner des cellules dans les tableaux Markdown ?
Non. Les tableaux Markdown standard ne supportent pas colspan ni rowspan — chaque ligne doit avoir le même nombre de colonnes. La fusion de cellules nécessite des tableaux HTML. Si vous avez besoin de cellules fusionnées, rédigez le tableau en HTML et intégrez-le directement dans votre document Markdown.
Puis-je imbriquer des tableaux dans des tableaux Markdown ?
Non. Les tableaux Markdown ne peuvent pas être imbriqués. Chaque tableau est une grille plate de lignes et de colonnes. Si vous avez besoin de données hiérarchiques, envisagez d'utiliser des listes imbriquées, des tableaux séparés avec des en-têtes ou des tableaux HTML avec des éléments <table> imbriqués.