Markdown tables explained

The basic syntax

A Markdown table is rows of text separated by pipe characters (|), with a second row of dashes that tells the tool where the header ends:

| Document | Owner | Status    |
| -------- | ----- | --------- |
| Plan.md  | Team  | In review |
| Notes.md | Me    | Saved     |

That gives a three-column table with a bold header row and two rows of data. The spaces that line the pipes up are optional; they make the source easier to read but the tool ignores them. This unpadded version renders exactly the same:

|Document|Owner|Status|
|---|---|---|
|Plan.md|Team|In review|
|Notes.md|Me|Saved|

Tables are not part of the original Markdown rules. They come from GitHub Flavored Markdown (GFM), the extended version that GitHub popularised, and nearly every modern tool supports them. If a table shows up as a jumble of pipes, the tool you are using does not.

Aligning columns

Colons in the dash row set the alignment of each column:

| Left     | Centre   | Right    |
| :------- | :------: | -------: |
| text     | text     |     1.00 |
| more     | more     |    25.50 |

A colon on the left aligns left (the default), on both sides centres, and on the right aligns right, which is what you want for numbers.

Rules worth knowing

• The header row and the dash row are both required. A table without the dash row is just text with pipes in it.
• Each dash column needs at least three dashes in most tools. |---| works; |-| may not.
• Every row should have the same number of cells. Most tools forgive a missing cell by leaving it empty, and ignore extra ones, but the results vary.
• The outer pipes are optional. a | b works as well as | a | b |. Many people keep them for clarity.
• A pipe inside a cell must be escaped as \|, or the tool will read it as a column break. This catches people writing about shell commands or regular expressions.
• Cells are single lines. Markdown tables have no multi-line cells and no merged cells. Some tools accept <br> inside a cell for a line break; not all do.
• Inline formatting works inside cells: bold, italics, code and links are fine. Lists and headings are not.

Common mistakes

The table renders as plain text

Usually the dash row is missing, or there is no blank line between the table and the paragraph above it. Add a blank line before the table.

One row has its columns shifted

A pipe inside a cell was not escaped, or a cell was left out. Count the pipes in that row against the header.

The last column is missing

If a row ends with a cell that contains only spaces, some tools drop it. Put a placeholder such as a dash in empty cells.

The table is fine on GitHub but broken elsewhere

The other tool probably does not support GFM tables, or supports a stricter version. Check whether it says it supports GitHub Flavored Markdown.

Coping with wide tables

Reports and coding agents produce tables with six, eight or ten columns, each cell a sentence long. In source view such a table is a wall of pipes that no amount of alignment makes readable. Three approaches help:

• Read it in a document view, where columns become real columns. This is the single biggest improvement. Nice Markdown shows tables alongside the rest of the document and has a Wide layout that gives a big table the full window.
• Turn columns into rows when the table is yours to restructure. A two-column table of "Option" and "Notes" often reads better than a six-column comparison.
• Check the output before printing. A very wide table may need landscape or a smaller font when it goes to paper or PDF. Nice Markdown's PDF export includes tables, and very wide ones are worth a look in the result.

Editing tables

In source view, you edit the text between the pipes; alignment spaces do not matter, so do not spend time re-aligning them. In a visual editor you edit the cell as you would in a word processor. One thing to know about Nice Markdown specifically: when you change a table in the Visual view, it rewrites that one table (and may tidy its spacing) but leaves every other line of the file exactly as it was, which keeps the change small when you look at it in Git.

Common questions

Can I merge cells or span columns?

Not in Markdown. If you need merged cells, the usual workaround is an HTML table inside the Markdown file, which some tools render and others do not.

Can I put a list inside a cell?

Not a real one. Some people write items separated by <br> or semicolons. If the content needs a list, it probably wants to be a section, not a table.

Is there a quick way to generate a table?

Many editors have a table generator or a paste-from-spreadsheet feature. Coding agents are very good at producing tables; describe the columns and rows and ask for GFM.