Tables in Markdown
Separate columns with | and put a row of dashes under the header. This guide covers alignment, formatting inside cells, escaping pipes, line breaks, and what to do when Markdown tables are not enough.
Quick answer
How do you make a table in Markdown?
Write the header cells between pipes, then a row of dashes, then one line per row: | Name | Role |, | --- | --- |, | Ana | Design |. Colons in the dash row set the alignment. Tables come from GitHub Flavored Markdown and work in most editors and on GitHub.
| Name | Role | Since |
| --- | --- | --- |
| Ana | Design | 2021 |
| Ben | Engineering | 2019 |Result
| Name | Role | Since |
|---|---|---|
| Ana | Design | 2021 |
| Ben | Engineering | 2019 |
Table syntax and examples
The columns in the source do not need to line up; the renderer builds the grid from the pipes.
Column alignment
A colon on the left of the dashes aligns left, colons on both sides center, and a colon on the right aligns right, which suits numbers.
| Item | Qty | Price |
| :--- | :---: | ---: |
| Apples | 3 | 1.20 |
| Pears | 12 | 4.80 |Result
| Item | Qty | Price |
|---|---|---|
| Apples | 3 | 1.20 |
| Pears | 12 | 4.80 |
Formatting inside cells
Cells can hold bold text, inline code, links, images and strikethrough, but no lists or code blocks.
| Option | Default | Notes |
| --- | --- | --- |
| `--force` | **off** | Skips [checks](https://example.com/checks) |
| `--quiet` | on | ~~Verbose~~ Silent output |Result
| Option | Default | Notes |
|---|---|---|
--force | off | Skips checks |
--quiet | on |
Pipes and line breaks in cells
Escape a pipe in a cell as \|, even inside code. Use <br> to start a new line in a cell.
| Operator | Meaning |
| --- | --- |
| `a \| b` | a or b |
| `&&` | Both must be true,<br>checked left to right |Result
| Operator | Meaning |
|---|---|
a | b | a or b |
&& | Both must be true, checked left to right |
Minimal syntax
The outer pipes and the spacing are optional. Lining up the columns only makes the source easier to read.
Name | Role
--- | ---
Ana | Design
Ben | EngineeringResult
| Name | Role |
|---|---|
| Ana | Design |
| Ben | Engineering |
Empty header
A table always has a header row. Leave its cells empty when the table does not need one.
| | |
| --- | --- |
| Monday | Gym |
| Tuesday | Piano |Result
| Monday | Gym |
| Tuesday | Piano |
Merged cells with HTML
Markdown tables cannot merge cells. Where HTML is allowed, write an HTML table with colspan or rowspan.
<table>
<tr><th colspan="2">Opening hours</th></tr>
<tr><td>Mon–Fri</td><td>9:00–18:00</td></tr>
<tr><td>Sat</td><td>10:00–14:00</td></tr>
</table>Result
| Opening hours | |
|---|---|
| Mon–Fri | 9:00–18:00 |
| Sat | 10:00–14:00 |
Tables in popular apps
Every app that follows GitHub Flavored Markdown shows tables. Chat apps do not.
| App | Support | Notes |
|---|---|---|
| GitHub / GitLab | Supported | Tables with alignment; wide tables scroll sideways. |
| Obsidian | Supported | Tables show in reading view and live preview. |
| VS Code / Typora | Supported | Tables show in the preview; Typora edits them as a grid. |
| Supported | Tables work in posts and comments. | |
| Discord / Slack | Not supported | Tables appear as plain text; a code block keeps the columns lined up. |
Questions and answers
How do I align text in a table column?
:--- aligns left, :---: centers and ---: aligns right.Can I merge cells in a Markdown table?
colspan or rowspan where HTML is allowed.How do I add a line break inside a cell?
<br> where the line should break. A real line break ends the row.How do I put a pipe character in a cell?
\|. This is needed inside code spans as well.Why is my table not rendering?
Can I put a list or code block in a cell?
<br> between items, or an HTML table where HTML is allowed.