Markdown table syntax: alignment, pipes, line breaks and more
The pipe-and-dash table syntax that GitHub, GitLab, Reddit, Obsidian and most Markdown apps understand, with the awkward cases answered.
The basic table
| Tool | Runs in | Free |
|-----------|-----------|------|
| Formatter | Browser | Yes |
| Linter | Terminal | Yes |Rules that matter:
- The header row is required. There's no header-less table in GitHub-style Markdown; if you don't want one, put short labels there.
- The divider row must have the same number of cells as the header, or the whole thing is shown as plain text. Three dashes per cell is the usual habit.
- The outer pipes and the neat spacing are optional.
a | bon one line and--|--on the next is a valid table; lining columns up just makes the source easier to read. - Body rows with too few cells get empty cells; extra cells are dropped.
- Leave a blank line before the table, especially after a paragraph, so every app spots it.
Aligning columns
| Left | Centre | Right |
|:---------|:--------:|------:|
| apples | 3 boxes | 1.20 |
| pears | 10 boxes | 12.50 |Right-align numbers so the digits line up. Without a colon, the app decides (usually left).
The awkward cases
| You want | Write |
|---|---|
| A pipe character in a cell | \| (also inside `code` in GitHub-style Markdown) |
| A line break inside a cell | <br>: every row must stay on one source line |
| A list inside a cell | Not possible; fake it with • one<br>• two |
| Bold, links, code in a cell | Works as normal: **yes**, [docs](/url) |
| An empty cell | Leave it blank: | a | | c | |
| Merged cells (colspan/rowspan) | Not supported; use an HTML <table> if your app allows HTML |
| Column widths | Not supported; the app sizes columns to the content |
Where tables work
Tables aren't part of original Markdown or plain CommonMark. They come from the GitHub Flavored Markdown (GFM) extension, which GitHub, GitLab, Reddit, Obsidian, Notion imports, Typora, VS Code's preview and most static-site generators support. Some chat apps that “support Markdown” don't render tables at all, so check before you paste a big one into a message.
From a spreadsheet to a Markdown table
Typing pipes by hand gets old fast. In the Markdown editor, switch to “HTML or rich text → Markdown” and paste cells copied from a spreadsheet or a table on a web page; it writes the Markdown table for you, then the preview shows whether it came out right. Its checker also flags rows with the wrong number of cells. If your data is a CSV file, the CSV to JSON converter helps you clean it up first.
Questions
How do I make a table in Markdown?
Write a header row with cells separated by pipes, then a divider row of dashes (one group per column), then one line per row. Most apps that use GitHub-style Markdown will render it.
How do I center a column in a Markdown table?
Put a colon at both ends of that column's dashes in the divider row, like :---:. A colon only on the right (---:) right-aligns it.
How do I add a line break in a Markdown table cell?
Use the HTML tag <br>, because each table row has to stay on a single line of source. Most renderers that support tables allow it.
Can Markdown tables merge cells?
No. GitHub-style tables have no colspan or rowspan. If you need merged cells, write an HTML table instead, where the app allows HTML.
Published .