How to make a table in Markdown:syntax, alignment and multiline cells.

The basic Markdown table syntax

Tables are part of GitHub Flavored Markdown (GFM), the dialect used by GitHub, GitLab and most Markdown apps. A table needs three things:

1. A header row

   The names of the columns, separated by pipes: | Name | Role |.

2. A delimiter row

   A line of dashes, one group per column, directly under the header: | --- | --- |. It must have as many cells as the header, or the text stays plain text and no table appears.

3. The rows

   One line per row, cells separated by pipes. A row with too few cells is filled with empty ones; extra cells are dropped. The table ends at the first blank line.

| Name  | Role     |
| ----- | -------- |
| Alice | Designer |
| Bob   | Engineer |

This is what a reader sees:

The pipes at the start and the end of each line are optional, but they make the table easier to read. The columns do not have to line up in the source; the padding above is only for people. Cells can hold bold, italic, code, links and images.

Markdown table alignment

Put a colon at the left, the right or both ends of a column's dashes:

| Item   | Qty | Price |
|:-------|:---:|------:|
| Pencil |  12 |  $1.50 |
| Ruler  |   3 |  $4.00 |

The alignment applies to the whole column, header included. It is set once in the delimiter row, not cell by cell. Right-align numbers so the digits line up.

A pipe or a second line inside a cell

A pipe ends a cell, so a pipe that is part of the text needs a backslash. GFM applies this even inside inline code:

| Command            | Meaning          |
|--------------------|------------------|
| `a \| b`           | a pipe, in code  |
| Either \| or       | a pipe, in text  |

A pipe table has one line per row, so a cell cannot hold a real line break or a second paragraph. The usual way round it is the HTML tag <br>:

| Step  | What to do                          |
|-------|-------------------------------------|
| Build | Run the build.<br>Fix any errors.  |
| Ship  | Tag the release.<br>Push the tag.  |

The same trick gives a multiline cell on GitHub and in most other apps that accept HTML. A Markdown list does not work inside a cell; if a cell needs a list, write <br> between short items or move the list out of the table.

Wide tables and long text

Markdown has no setting for column width and no way to merge cells; the app that shows the table decides how it fits. A few habits keep a table readable everywhere:

• Keep cells short, a word or a number. Put the long explanation in a sentence under the table.
• Use fewer columns. If a table has eight, turn it around: make the columns the items and the rows the properties.
• Do not pad the source to line up the columns on a table you edit often; one changed cell would mean re-spacing every line.
• For merged cells, row spans or a caption, write the table in HTML. Most Markdown apps show a plain <table>.

Why a Markdown table does not render

• No delimiter row. The line of dashes is what makes the text a table.
• The cell counts differ. If the header has three cells and the delimiter row two, nothing renders.
• An unescaped pipe in a cell splits it in two. Write \|.
• A blank line inside the table. The table ends there; the rest is plain text.
• The app has no tables. Tables are not in the original Markdown or in CommonMark's core. They come from GFM, so a minimal parser shows the pipes as text.

To see the result before you commit, open the file in a Markdown reader. DotMD shows tables rendered and is free to read with. In DotMD Editor, Insert → Table puts a ready three-column table into your file, and the live preview redraws it as you type.

Questions about Markdown tables

More questions