A table organises content into rows and columns with a header row. It is written using | pipe characters to divide columns and a separator row of - dashes to mark the boundary between the header and the body. Column alignment is controlled by adding : to the separator row.
| Destination | Best Month | Budget |
| --- | --- | --- |
| Lisbon | May | £ |
| Reykjavik | June | £££ |
| Kyoto | April | ££ |
Alignment options on the separator row:
| Left Aligned | Centre Aligned | Right Aligned |
| :--- | :---: | ---: |
| text | text | text |
| Destination | Best Month | Budget |
|---|---|---|
| Lisbon | May | £ |
| Reykjavik | June | £££ |
| Kyoto | April | ££ |
Alignment options on the separator row:
| Left Aligned | Centre Aligned | Right Aligned |
|---|---|---|
| text | text | text |
Best Practice
- Keep column content short and scannable — tables are for structured comparison, not prose.
- Use alignment (
---:for right,:---:for centre) to suit the column's content type: right-align numbers, centre-align ratings or symbols, left-align text. - Do not rely on the pipe characters being perfectly aligned in source — most renderers ignore extra whitespace.
Notes
Alignment
Colons on the separator row control text alignment within a column:
| Left aligned | Centre aligned | Right aligned |
| :--- | :---: | ---: |
| text | text | 42 |
Left alignment is the default when no colon is present.
Inline Formatting in Cells
Standard inline Markdown — emphasis, strong, inline code, and links — works inside table cells. Block elements such as lists or fenced code blocks cannot appear inside a cell.
Escaping Pipes
To include a literal | character inside a cell, escape it with a backslash: \|.
Markdown Flavour Support
Not in the original spec or CommonMark; supported by GFM and most modern flavours.
Flavour Support Detail
| Flavour | Support | Notes |
|---|---|---|
| Original Markdown | No | Not defined in the original spec. |
| CommonMark | No | Explicitly out of scope in the CommonMark spec. |
| GitHub Flavored Markdown | Yes | Defined in GFM; the most widely adopted table syntax. |
| Pandoc Markdown | Yes | Full support; also supports multi-line cells via grid tables. |
Practical Examples
- Holiday comparison table: Compare destinations across a few key factors so readers can scan the options at a glance.
| Destination | Best season | Highlights |
| --- | --- | --- |
| Porto | Spring | Wine, tiles, riverside |
| Dubrovnik | Early autumn | Old town, coast |
| Valletta | Winter | Culture, mild weather |
| Destination | Best season | Highlights |
|---|---|---|
| Porto | Spring | Wine, tiles, riverside |
| Dubrovnik | Early autumn | Old town, coast |
| Valletta | Winter | Culture, mild weather |
- Book log for a reading challenge: Track what you have read across the year with a simple status column.
| Title | Author | Status |
| --- | --- | --- |
| Piranesi | Susanna Clarke | ✅ Read |
| The Goldfinch | Donna Tartt | 📖 Reading |
| Hamnet | Maggie O'Farrell | 🗒️ To read |
| Title | Author | Status |
|---|---|---|
| Piranesi | Susanna Clarke | ✅ Read |
| The Goldfinch | Donna Tartt | 📖 Reading |
| Hamnet | Maggie O'Farrell | 🗒️ To read |
- Recipe ingredient amounts scaled for different servings: Right-align the number columns so quantities line up cleanly for easy comparison.
| Ingredient | 2 servings | 4 servings | 8 servings |
| --- | ---: | ---: | ---: |
| Plain flour | 100g | 200g | 400g |
| Butter | 50g | 100g | 200g |
| Sugar | 75g | 150g | 300g |
| Ingredient | 2 servings | 4 servings | 8 servings |
|---|---|---|---|
| Plain flour | 100g | 200g | 400g |
| Butter | 50g | 100g | 200g |
| Sugar | 75g | 150g | 300g |