Dans cet article
What Are Markdown Tables?
Markdown tables use pipe characters (|) and hyphens (-) to create structured tabular data within plain text documents. They are part of GitHub Flavored Markdown (GFM) and are supported by most Markdown renderers including GitHub, GitLab, VS Code, and static site generators.
Tables in Markdown are designed for simple data presentation — column headers, separator row, and data rows. They render as proper HTML tables in the output, making them ideal for documentation, README files, and technical writing without any HTML knowledge.
Markdown Table Syntax
A Markdown table consists of three parts: the header row, the separator row, and one or more data rows.
- Header row — the first row defines column names, separated by pipe characters (|). Leading and trailing pipes are optional but recommended for clarity.
- Separator row — the second row uses hyphens (---) between pipes to separate the header from data. At least three hyphens per column are required.
- Data rows — each subsequent row contains cell values separated by pipes. Cells do not need to align visually, though aligned columns improve source readability.
- Escaping pipes — if cell content contains a literal pipe character, escape it with a backslash (\|) to prevent it from being interpreted as a column separator.
Column Alignment Options
Column alignment is controlled by adding colons to the separator row. This determines how text is aligned within each column.
- Left alignment (default) — use :--- or --- in the separator. Text aligns to the left edge of the column. This is the default when no colons are specified.
- Center alignment — use :---: in the separator. Text is centered within the column. Useful for status labels, categories, or short values.
- Right alignment — use ---: in the separator. Text aligns to the right edge. Ideal for numeric values, prices, counts, and measurements.
Essayez gratuitement — sans inscription
Generer des tables Markdown →Common Use Cases
Markdown tables are used wherever structured data needs to be presented in documentation.
- README documentation — project feature comparison tables, installation requirements, supported platforms, and version compatibility matrices
- API documentation — endpoint references with method, path, description, and parameter tables for each route
- Comparison tables — side-by-side feature comparisons, pricing tiers, and tool evaluations in blog posts and technical reviews
- Changelogs — version history tables with date, version number, and description of changes for each release
Tips and Best Practices
Following these guidelines helps keep your Markdown tables readable in both source and rendered form.
- Keep columns aligned in source — pad cells with spaces so columns line up visually. Most editors and our generator handle this automatically. Aligned source is much easier to review in pull requests.
- Avoid complex content in cells — Markdown tables do not support multi-line cell content, block elements, or nested tables. Keep cell content short and simple. For complex data, consider using HTML tables instead.
- Limit column count — tables with more than 5-6 columns become hard to read on smaller screens. Consider splitting wide tables into multiple focused tables or using a different format for very wide data.
Frequently Asked Questions
Is there a limit to cell content in Markdown tables?
There is no technical character limit for cell content, but Markdown table cells are single-line only. You cannot include line breaks, paragraphs, or block-level elements like lists inside a cell. For complex cell content, use HTML tables with <td> elements that support any HTML content.
Can I merge cells in Markdown tables?
No. Standard Markdown tables do not support colspan or rowspan — every row must have the same number of columns. Cell merging requires HTML tables. If you need merged cells, write the table in HTML and embed it directly in your Markdown document.
Can I nest tables inside Markdown tables?
No. Markdown tables cannot be nested. Each table is a flat grid of rows and columns. If you need hierarchical data, consider using nested lists, separate tables with headings, or HTML tables with nested <table> elements.