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.

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 example first 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:

  1. Repeat the value so the table stays regular.
  2. Split it into two smaller tables.
  3. 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.