Markdown Tables: The Complete Guide
Tables are one of the most useful parts of Markdown, and one of the easiest to get wrong. This guide goes from the basic format to alignment, line breaks, special characters and converting from spreadsheets. To try the examples, paste them into the online Markdown editor and see the result instantly.
Basic syntax
A table has three parts: a header row, a separator row and data rows. Separate columns with |.
| Name | Team | Ext. |
| --- | --- | --- |
| Alice | Sales | 101 |
| Bob | Design | 205 |
Result:
| Name | Team | Ext. |
|---|---|---|
| Alice | Sales | 101 |
| Bob | Design | 205 |
Key points:
- The
---separator row is required, with at least three dashes per column. - The outer
|characters are optional, but they make the table easier to read. - Every row should have the same number of columns as the header.
- Leave a blank line before and after the table.
Column alignment
Add colons : to the separator row:
| Left | Center | Right |
| :--- | :---: | ---: |
| Apples | 10 | $30 |
| Bananas | 5 | $15 |
| Left | Center | Right |
|---|---|---|
| Apples | 10 | $30 |
| Bananas | 5 | $15 |
Right-align numbers and prices so they're easy to compare.
Code, links and bold text in cells
Inline Markdown works inside cells:
| Command | Description |
| --- | --- |
| `npm install` | Install packages, see the [docs](https://docs.npmjs.com/) |
| **Required** | This field must be filled in |
Showing a pipe character in a cell
A | is read as a column separator, so escape it with a backslash:
| Operator | Meaning |
| --- | --- |
| `a \| b` | Bitwise OR |
Line breaks inside a cell
Standard Markdown tables don't support line breaks inside a cell; each row must stay on one line. Common workarounds:
- GitHub accepts
<br>, for examplefirst line<br>second line. - Moread doesn't run HTML tags for security, so
<br>is shown as text. Split the content into separate rows or use a list instead.
Merged cells
Standard Markdown tables can't merge cells. Alternatives:
- Repeat the value so the table stays regular.
- Split it into two smaller tables.
- For complex content, a list or subheadings are often clearer.
Converting from Excel or Google Sheets
Copying cells from a spreadsheet gives you tab-separated text. To convert it:
- Replace tabs with
|in a text editor, add|at the start and end of each row, and insert the separator row. - Or use an "Excel to Markdown" converter.
Then paste it into the online editor to check the columns.
Wide tables
Tables with many columns can overflow on phones. Moread lets tables scroll sideways so they don't break the layout. When writing, you can also:
- Drop columns that aren't essential.
- Use short keywords in cells and explain details below the table.
Quick template
| Item | Qty | Amount |
| :--- | ---: | ---: |
| Item one | 1 | 100 |
| Item two | 2 | 250 |
| **Total** | **3** | **350** |
For more syntax, see the Markdown syntax guide; to turn your tables into a report, see Markdown to PDF.