Tables in Markdown

Tables are the one piece of Markdown that looks intimidating in the source and turns out to be trivial: a row is a line with pipes between the cells, and a divider row of dashes tells the parser that the line above it was the header.

Edit the table below — add a column, change the alignment, delete a row — and watch the preview keep up.

| Feature        | Free | Pro |
|:---------------|:----:|----:|
| Live preview   |  ✓   |  ✓  |
| PDF export     |  ✓   |  ✓  |
| Version history|  —   |  ✓  |
| EPUB export    |  —   |  ✓  |

The three rules

1. Every row is a line, with | between cells. The leading and trailing pipes are optional, but keeping them makes the source far easier to read.
2. The second line is the divider, made of at least three dashes per column. It is what turns the first row into a header — without it, you do not have a table at all.
3. Column count comes from the divider. Extra cells in a row are dropped; missing ones render empty.

Alignment

Colons in the divider row set how each column is aligned. This is the part people look up every time:

| Left | Center | Right |
|:-----|:------:|------:|
| a    |   b    |     c |
| long text | still centred | 42 |

• :--- aligns left (the default)
• :--: centres
• ---: aligns right

Right-align your number columns. It is a small thing that makes a table of prices or measurements dramatically easier to scan.

The pipes do not need to line up

This is worth saying clearly, because a lot of people waste time on it:

| Feature | Free | Pro |
|---|---|---|
| Preview | yes | yes |
| A much longer feature name | no | yes |

That renders exactly as neatly as a perfectly padded source. Aligning the pipes by hand is purely for the comfort of whoever reads the raw file — and an editor with a live preview makes it unnecessary, because you are looking at the result rather than the source.

Formatting inside cells

Cells accept inline Markdown: bold, italic, code, links and images all work.

| Element | Syntax | Docs |
|---------|--------|------|
| **Bold** | `**text**` | [guide](/markdown-guide) |
| *Italic* | `*text*` | [guide](/markdown-guide) |

What tables cannot do

Markdown tables are deliberately simple, and these limits are not bugs:

• No multi-line cells. A cell is one line. To put a line break inside one you need <br>, which costs you portability.
• No merged cells. There is no rowspan or colspan.
• No nested tables, lists or code blocks inside a cell.
• No captions, though a bold line or a paragraph right above the table does the job.

If you genuinely need any of those, you need HTML, and that is usually a sign the information wants a different shape — a list of subsections, for instance.

Escaping a pipe

A literal | inside a cell would end it. Escape it with a backslash:

| Command | Meaning |
|---------|---------|
| `a \| b` | pipe a into b |

Common mistakes

Forgetting the divider row. Without the dashes, the lines render as ordinary paragraphs with visible pipes. This is the number one reason a table “does not work”.

No blank line before the table. If the table starts on the line straight after a paragraph, many parsers fold it into that paragraph. Leave a blank line.

Fewer than three dashes. |-|-| works in some parsers and fails in others. Use at least three per column.

Expecting tables in plain Markdown. Tables are a GitHub Flavored Markdown extension, not part of the 2004 original. Every modern editor supports them, but a very old or minimal parser may not.

FAQ

How do I create a table in Markdown?

Write your header row with | between the cells, put a line of dashes under it — |---|---| — and then one line per row. The divider row is what makes it a table; without it the pipes render as plain text.

How do I align columns in a Markdown table?

Add colons to the divider row. :--- is left, :--: is centre and ---: is right. Alignment is per column and applies to both the header and the body.

Can a Markdown table cell contain multiple lines?

Not in standard Markdown — a cell is a single line. You can insert <br> if your renderer allows raw HTML, but that makes the file less portable. If a cell needs several lines of content, the information is usually better presented as a list or as subsections.

Do the pipes need to line up in the source?

No. The table renders identically whether or not the columns are padded to the same width. Neat source is only for human readers of the raw file.

How do I put a pipe character inside a table cell?

Escape it with a backslash: \|. Inside inline code you still need the backslash, because the table is parsed before the code span.