How to make a table in Markdown

The syntax

Write each row on its own line, with | between the cells. The second line is the delimiter row: one cell of dashes for each column.

| Planet  | Diameter (km) | Moons |
|---------|--------------:|------:|
| Mercury |          4879 |     0 |
| Venus   |         12104 |     0 |
| Earth   |         12756 |     1 |
| Mars    |          6792 |     2 |

• The first row is the header. A Markdown table always has one. Its cells are bold.
• The delimiter row must have as many cells as the header. Otherwise the table is not a table: it shows as text with | signs in it.
• The colons in the delimiter row align the columns. See Align the columns.

The spaces that line up the | signs are only for people who read the code. The | at the start and at the end of a row can be left out too. This code makes the same table:

Planet | Diameter (km) | Moons
--- | ---: | ---:
Mercury | 4879 | 0
Venus | 12104 | 0
Earth | 12756 | 1
Mars | 6792 | 2

Even so, write the outer | signs. They make the rows easy to see, and a table of one column needs them. Write at least three dashes in each cell of the delimiter row: a line that starts with a single - can be read as a list.

Align the columns

A colon in the delimiter row sets the alignment of its column:

| Item      | Qty | Price |
|:----------|:---:|------:|
| Coffee    |  2  |  7.00 |
| Croissant |  1  |  2.20 |
| **Total** |     |  9.20 |

The alignment is for the whole column, the header included. You cannot align one cell in another way. Align numbers to the right, so that the units, tens and hundreds are one under the other, and give them the same number of decimal places. The empty cell in the last row is an empty cell: write its | signs with nothing, or only spaces, between them.

Formatting, links and line breaks in cells

A cell can hold what Markdown allows in a line of text: bold, italic, `code`, ~~strikethrough~~, links, images and emoji.

| Option      | Default | What it does                              |
|-------------|---------|-------------------------------------------|
| `--output`  | `out/`  | The folder for the files                  |
| `--format`  | `html`  | `html` \| `pdf` \| `epub`                 |
| `--strict`  | off     | **Stops** at the first error              |
| `--ignore`  |         | Files to skip.<br>Repeat it for each file |
| `--log`     | off     | See [Logging](#logging)                   |

• A | in a cell must be written as \|. Otherwise it ends the cell. This is true in code too: on GitHub, `a \| b` shows as a | b in a cell.
• A cell is one line of code. To break its text into lines, write <br>. GitHub, GitLab and most other sites show it. Programs that do not allow HTML show <br> as text.
• No blocks in a cell. Lists, headings, quotes, code blocks and task list check boxes do not work in a cell. For a short list, use <br> and a • or a dash at the start of each line. For a done/not done column, use ✅ and ❌.
• An image in a cell is ![text](image.png). To make it smaller on GitHub, write an HTML <img src="image.png" width="80">.

Merged cells, widths and captions

Markdown tables cannot merge cells, set column widths or have a caption. If you need these, write the table in HTML. GitHub, GitLab and many other sites show HTML tables in Markdown files:

<table>
  <tr>
    <th rowspan="2">Planet</th>
    <th colspan="2">Size</th>
  </tr>
  <tr>
    <th>Diameter (km)</th>
    <th>Mass (10<sup>24</sup> kg)</th>
  </tr>
  <tr>
    <td>Earth</td>
    <td align="right">12756</td>
    <td align="right">5.97</td>
  </tr>
  <tr>
    <td>Mars</td>
    <td align="right">6792</td>
    <td align="right">0.642</td>
  </tr>
</table>

• colspan="2" merges a cell with the next one in its row. rowspan="2" merges it with the cell under it. The cells that a merged cell covers are not written. See the HTML tables guide for more.
• Do not leave empty lines in the HTML. After an empty line, Markdown reads the lines again: a line indented by four spaces shows as code.
• GitHub removes style attributes and <style> elements, so you cannot set colours or borders. align="right" and an image's width do work.

Column widths in a Markdown table follow the text. A long text makes a wide column. To give a table a caption, write a line of text above it, for example in bold. Some Markdown programs add more to the syntax: pandoc and MultiMarkdown have captions, and pandoc's grid tables can merge cells. Such tables work only in that program.

Common mistakes

When a table is broken, it usually shows as lines of text with | signs. These are the causes, from the most common:

This is the line under the table, on GitHub:

| Planet | Moons |
|--------|------:|
| Earth  |     1 |
| Mars   |     2 |
Source: NASA

A table without a header is not possible. If the first row is not a header, write a header row of empty cells (| | |). GitHub shows it as a thin empty row.

Where Markdown tables work

The first Markdown (2004) had no tables. PHP Markdown Extra added this syntax, and GitHub Flavored Markdown (GFM) made it common. Most programs now read tables as GFM does:

• Work: GitHub (README files, issues, pull requests, wikis, gists), GitLab, Bitbucket, Stack Overflow, Reddit, Obsidian, Typora, Jupyter notebooks, the Markdown preview of VS Code, pandoc (-f gfm or its default Markdown), and static site generators such as Hugo, Jekyll, MkDocs and Docusaurus.
• Need a setting: Python-Markdown, with the tables extension. Others, such as markdown-it, read tables by default, but a site can turn them off.
• Do not work: Discord, Slack, WhatsApp and Telegram messages. See the next section.
• Their own syntax: Jira and Confluence wiki markup (||heading||) and MediaWiki ({| … |}, see the MediaWiki tables guide).

Tables in Discord, Slack and WhatsApp

Chat programs show Markdown's bold, italic and code, but not its tables. A Markdown table there shows as lines of | signs that do not line up, because the font's letters have different widths. Send a text table in a code block instead. In a code block, each character is as wide as the others, so the columns line up:

```
+---------+---------------+-------+
| Planet  | Diameter (km) | Moons |
+---------+---------------+-------+
| Mercury |          4879 |     0 |
| Venus   |         12104 |     0 |
| Earth   |         12756 |     1 |
| Mars    |          6792 |     2 |
+---------+---------------+-------+
```

+---------+---------------+-------+
| Planet  | Diameter (km) | Moons |
+---------+---------------+-------+
| Mercury |          4879 |     0 |
| Venus   |         12104 |     0 |
| Earth   |         12756 |     1 |
| Mars    |          6792 |     2 |
+---------+---------------+-------+

• Type ``` on the line before the table and on the line after it. Discord, Slack, Telegram and WhatsApp all show the text between them in a fixed-width font.
• Keep the table narrow, about 40 characters or less for phones. A long line wraps, and the columns no longer line up. Use short headers, or put the table on its side (more rows, fewer columns).
• Emoji and characters such as Chinese take the width of two letters. Our generators count them so, but some fonts draw emoji a little wider or narrower, and the lines of their rows may stick out.

In our editor Make the table in our Text Tables Generator, which draws the lines for you. See the text tables guide.

Convert a table to Markdown and back

From Excel, Google Sheets or a CSV file

Select the cells in the spreadsheet and copy them. Open the Markdown Tables Generator, click its top left cell and paste. The Markdown code is under the table. To import a file, select File › Import CSV or Excel file.

From a web page or HTML

Select the table on the web page and copy it. In the generator, select File › Paste table data, paste it in the box and click Load. HTML code of a table works too. Merged cells are split, because Markdown has none.

Change a Markdown table, or move it to a spreadsheet

Paste the Markdown code in File › Paste table data and click Load. The cells come in the generator's grid, with the alignment of the columns, and you can change them there. To move the table to a spreadsheet, click a cell of the table, press Ctrl+A to select all cells and Ctrl+C to copy them, and paste them in Excel or Google Sheets. Or select File › Download as CSV.

With code

To make the table from data each time the data changes:

# pandoc: a CSV file or an HTML page to a GitHub Markdown table
pandoc data.csv -t gfm -o table.md
pandoc page.html -t gfm -o page.md

# Python: pandas writes Markdown with the tabulate package
df.to_markdown('table.md', index=False)

Make the table without writing the code

In our Markdown Tables Generator, you type the cells in a grid, as in a spreadsheet, and it writes the code with the | signs lined up. It escapes each | in the cells for you. Markdown typed in a cell, such as **bold** or a link, goes into the code as it is.

• Align a column: select a cell of the column and click an alignment button on the toolbar. The generator uses the alignment of the column's cell in the first row.
• Bold and italic: select cells and click the toolbar's B or I button.
• Line breaks in a cell: select Line breaks as <br>. Otherwise a line break in a cell becomes a space.
• Small changes in Git: select Compact mode. Lined-up columns look good, but when one cell gets longer, every line of the table changes. In compact mode, only the changed row does.
• See the result: click Preview.