How to make tables in Markdown

The basic structure

A Markdown table has three parts: a header row, a delimiter row and any number of body rows. Pipes (|) separate the cells. The delimiter row consists of hyphens, one group per column, and tells the renderer that the lines above and below form a table.

| Fruit  | Price | In stock |
| ------ | ----: | :------: |
| Apple  |  1.20 |   yes    |
| Pear   |  0.90 |    no    |
| Banana |  0.35 |   yes    |

The rules that matter

The shortest valid form works, but it is harder to read:

Name | Role
--- | ---
Ada | Admin
Linus | Editor

• The header row is required. GFM has no tables without a header.
• The delimiter row must have exactly as many cells as the header row, otherwise the block is not recognized as a table.
• Each delimiter cell needs at least one hyphen. Three is the common convention and is understood everywhere.
• Body rows with fewer cells are filled with empty cells; extra cells are ignored.
• Leading and trailing pipes are optional, but they make the source easier to read. For a single-column table, keep them.
• The columns do not have to line up in the source. Spaces around cell content are trimmed.
• The table ends at the first blank line or at the start of another block such as a heading or a list. Leave a blank line before the table as well.

Aligning columns

Colons in the delimiter row set the alignment of a whole column, header included. Right alignment is useful for numbers, so the decimal places line up.

Formatting inside cells

Cells may contain inline Markdown: bold, italic, code, links, images and strikethrough. Block elements are not possible: no lists, no headings, no code blocks and no paragraphs inside a cell.

| Command      | Description                |
| ------------ | -------------------------- |
| `git status` | Shows **changed** files    |
| `git log`    | See the [docs](https://git-scm.com/docs) |

Escaping the pipe character

A pipe inside a cell would start a new column. Write \| instead. In GFM this also applies inside code spans within a table: `a \| b` is displayed as a | b in code formatting.

| Operator | Meaning   |
| -------- | --------- |
| `a \| b` | a or b    |
| \|x\|    | absolute value |

What Markdown tables can't do

The pipe syntax is deliberately simple. If you need any of the following, you have to fall back to an HTML table, and only where your renderer allows HTML:

• Merged cells (no colspan or rowspan)
• Multiple paragraphs or lists within a cell
• Captions
• Fixed column widths
• Tables without a header row

Line breaks in cells

A cell must fit on one line of source. Many renderers, including GitHub, accept the HTML tag <br> inside a cell to force a line break. Whether that works elsewhere depends on whether the renderer lets HTML through.

Writing tables on iPhone and iPad

Typing pipes and hyphens on a phone keyboard is fiddly. In Markdown Editor, the formatting bar above the keyboard inserts a table with one tap, and the preview shows it formatted as a real table; on iPad you see the source and the live preview side by side, so a missing pipe stands out immediately. Your documents stay plain .md files in the Files app. With Markdown Editor Pro you can export them as formatted PDF or HTML.