The basic table
| Fruit | Colour | Price |
|--------|--------|-------|
| Apple | Red | 1.20 |
| Banana | Yellow | 0.50 |
This is what it shows:
| Fruit | Colour | Price |
|---|---|---|
| Apple | Red | 1.20 |
| Banana | Yellow | 0.50 |
Three kinds of rows:
- Header row: the column names.
- Dashes row: separates the header from the rest. It is required. Without it, there is no table.
- Data rows: one line per row.
Pipes | separate the cells. The pipes at the start and end of each line are optional, but they make the table easier to read.
The columns don't have to line up in your text. This works too:
| Fruit | Colour | Price |
|---|---|---|
| Apple | Red | 1.20 |
Leave an empty line before and after the table. The table ends at the first empty line.
Aligning columns
Add colons : to the dashes row:
| Left | Centre | Right |
|:-----|:------:|------:|
| a | b | 1.20 |
| aa | bb | 10.50 |
| Left | Centre | Right |
|---|---|---|
| a | b | 1.20 |
| aa | bb | 10.50 |
:---left:---:centre---:right (good for numbers)
Formatting inside a cell
Cells can hold bold, italics, code and links:
| Task | Status | Link |
|-----------|----------|------------------------------|
| Write | **Done** | [Notes](https://example.com) |
| `npm test`| *Running*| |
To put a pipe inside a cell, write it as \|. Otherwise it starts a new cell. This also applies inside code.
What tables can't do
- No merged cells. Every row has the same columns.
- No lists or paragraphs in a cell. A cell holds one line of text.
- The header and the dashes row must match. If the header has three cells, the dashes row needs three too. If not, you get plain text instead of a table.
- Rows can be shorter or longer. A short row gets empty cells. Extra cells at the end of a long row are dropped.
Wide tables
A table with many columns gets wide, especially on a phone. Some tips:
- Keep cells short. Move long text below the table.
- Split one big table into two smaller ones.
- Put the most important column first.
Quick ways to make a table
- From a spreadsheet: many online converters turn copied cells into a Markdown table.
- From an AI chat: ask for "a Markdown table" and say which columns you want. If the chat shows a formatted table, ask it to put the Markdown in a code block so you can copy the text.
Reading Markdown tables
In a plain text editor, a table stays as pipes and dashes. That is readable for small tables, but hard for big ones. A Markdown reader shows the real grid.
PilcrowMD shows Markdown tables on Android and Mac. Cells can show bold, italics, links and maths. On Android, a wide table scrolls sideways, so the columns don't get squeezed.
Common questions
Is a Markdown table the same everywhere? Mostly. Tables are part of GitHub Flavored Markdown, which most apps follow. A few very simple Markdown apps don't show tables at all.
Can I add a line break inside a cell? Not in standard Markdown. Some apps accept the HTML tag <br>, but not all.
Do I need to line up the pipes? No. It only makes the text easier to read.
Also on Mac: PilcrowMD for Mac (beta)