Markdown Table Syntax, Explained

A table in Markdown is a few lines of text with pipe characters (|) between the cells and a row of hyphens under the header. Write a header row, a delimiter row of hyphens, then one line per data row. GitHub, Pandoc and other renderers draw it as a grid.

A pipe inside a cell or a missing blank line breaks a table, and colons in the delimiter row change the alignment. Each rule below comes with an example you can copy.

How a Markdown table is built

Every table has three parts:

1. The header row. Cell names, separated by pipes.
2. The delimiter row. Hyphens under each header cell, also separated by pipes. The delimiter row tells the renderer that the lines above and below are a table.
3. The data rows. One line of text for each row of the table.

Here is a two-column table of Git commands:

| Command | What it does |
| --- | --- |
| git status | Lists new or changed files |
| git log | Shows the commit history |

A few rules decide whether it renders:

• Leave a blank line before the table. GitHub's documentation says a table needs one to render correctly. Without it, the table may show as plain text.
• The pipes at each end are optional. Command | What it does works too. Most people keep the outer pipes, because the rows are easier to read.
• The columns don't need to line up. Pandoc's manual calls an unaligned pipe table "perfectly legal (though ugly)". Padding with spaces only helps the person reading the raw text.
• Use three hyphens per column. GitHub's documentation asks for at least three in each column of the delimiter row. Pandoc also accepts a single hyphen, but three keeps the table valid on GitHub too.
• Keep the header. Pandoc says the header cannot be left out. To get a table with no visible header, give it a header row of empty cells.

Aligning the columns

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

| Item | Status | Price |
| :--- | :---: | ---: |
| Paper | In stock | 4.50 |
| Toner | Low | 62.00 |

• :--- aligns the column left. That is also what you get with no colon.
• :---: centres it.
• ---: aligns it right.

Right alignment suits columns of numbers, because the decimal points line up when the values have the same number of decimal places.

What can go inside a cell?

A cell holds one line of inline content. Bold, italics, inline code and links all work:

| Setting | Meaning |
| --- | --- |
| `--out` | Folder for the **converted** files |
| Docs | See [the manual](https://example.com) |

A pipe in your data splits the cell

The renderer reads every | as a column boundary, so a value such as a|b becomes two cells and shifts the rest of the row. Put a backslash before it, written \|, and the pipe shows as text.

Lists and paragraphs don't fit in a cell

Pandoc's manual states that pipe table cells cannot hold paragraphs or lists and cannot span several lines. A bullet list typed into a cell does not become a list.

What Markdown tables can't do

The pipe syntax has no way to merge two cells into one, across a row or down a column. It also has no nested tables, no cell colours and no column widths you can set by hand. Pandoc has one width control. When a table's text wraps, Pandoc sets each column's share of the page width from the number of hyphens in the delimiter row. A delimiter row of ---|- gives the first column three quarters of the width.

When a table needs merged cells or a list inside a cell, you have two choices:

• Split it. Two simple tables are often clearer than one complex one.
• Write an HTML table. Many Markdown renderers accept raw HTML, so <table> with colspan or rowspan can carry the merged cells. Check that your renderer allows HTML before you rely on it.

How to turn text or a spreadsheet into a table

Typing pipes is fine for three rows. For anything longer, let a tool write the syntax.

Convert text to a Markdown table

Put the values in comma- or tab-separated lines and save them as a .csv or .tsv file. Then drop the file onto MarkPrep's CSV page. It detects the delimiter and escapes any pipes in the data. The first line becomes the header row.

Convert a spreadsheet

Open MarkPrep's Excel page and drop in the .xlsx or .xls file. Each sheet becomes its own table under a heading.

Convert a table inside a document

MarkPrep's document converters turn tables into Markdown tables when the source file stores them as tables. A Word table becomes a pipe table with its first row as the header. A PDF table is rebuilt from the column positions of the text, which works best on simple grids.

Convert Markdown to a table you can read

To see the raw syntax drawn as a grid, paste it into the Markdown viewer. Any viewer that supports tables does the same.

Why is my Markdown table not rendering?

When the pipes show up as plain text, check these causes in order:

1. No blank line above the table. Add one between the paragraph and the header row.
2. A broken delimiter row. Each column needs its own run of hyphens, separated by pipes, directly under the header.
3. An unescaped pipe. See the section on pipes above.
4. A renderer without tables. Tables are an extension to the original Markdown. GitHub, Pandoc and MarkPrep's editor and viewer draw them, but an app that sticks to the original syntax shows the raw text.

If the table renders but looks wrong, compare the number of cells in each row. A row with fewer cells than the header usually means a missing pipe.

Building one with the table generator

MarkPrep's table generator gives you a grid of input boxes instead of raw syntax. It opens with three rows and three columns, headed Name, Role and Score.

1. Set the size with the Rows and Columns buttons. A table can have 2 to 20 rows and 1 to 10 columns.
2. Type into the cells. The top row is the header, and an empty header cell is filled in as "Column 1", "Column 2" and so on.
3. Read the Markdown below the grid. It updates as you type, with any pipes in your text escaped.
4. Click Copy and paste the result into your file.

With the starting headers and one row filled in, the output looks like this:

| Name | Role | Score |
| --- | --- | --- |
| Ada | Engineer | 99 |
|  |  |  |

Empty rows stay in the output as rows of blank cells, so remove any you don't need before you paste. The generator writes plain --- delimiters, so add the colons by hand if a column needs centring or right alignment. Headings, links, code and the other elements are on one page in the cheat sheet.