Markdown tables

The rules

• Keep the same number of cells in every row. A row with extra cells loses them, and a row with too few gets empty cells.
• The dash row needs at least one dash per column. Three, ---, is the habit because it is easy to see.
• The pipes at the start and end of each row are optional, but they make the table easier to read in the source.
• The columns do not have to line up in the source. This works too:

| Name | Role |
|---|---|
| Ana | Designer |
| Ben | Engineer |

Lining them up is only for people reading the plain text.

Align a column

Put colons in the dash row. A colon on the left aligns left, on both sides centers, on the right aligns right. Numbers read best aligned right.

| Item   | Qty | Price  |
| :----- | :-: | -----: |
| Paper  |  2  |  $4.00 |
| Ink    | 10  | $12.50 |
| Folder |  1  |  $0.80 |

Format text inside a cell

Bold, italic, code and links all work inside a cell.

| Command          | What it does                     |
| ---------------- | -------------------------------- |
| `git status`     | Shows **changed** files          |
| `git log`        | Lists commits, *newest first*    |
| `git help`       | Opens the [manual](https://git-scm.com/docs) |

Put a pipe inside a cell

A | ends the cell, so write it as \|.

| Operator | Meaning     |
| -------- | ----------- |
| `a \| b` | a or b      |
| `a & b`  | a and b     |

Start a new line inside a cell

A table row must stay on one line in the source, so use <br> where the cell should break.

| Day    | Plan                       |
| ------ | -------------------------- |
| Monday | Arrive<br>Dinner at eight  |
| Friday | Leave at noon              |

A table without a header

Markdown tables always have a header row. If you do not want one, leave the header cells empty. Some apps still draw an empty row at the top.

|   |   |
|---|---|
| Ana | Designer |
| Ben | Engineer |

Merge cells

Markdown tables cannot merge cells. If you need it, write the table in HTML, where colspan joins cells across columns and rowspan down rows. GitHub and MarkdownPaper both allow it.

<table>
  <tr><th colspan="2">Opening hours</th></tr>
  <tr><td>Weekdays</td><td>9 to 6</td></tr>
  <tr><td>Weekends</td><td>Closed</td></tr>
</table>

Checkboxes in a table

The task list syntax, [ ] and [x], only works at the start of a list item, so inside a table it shows as plain text. Use a word or a symbol instead.

| Task         | Done |
| ------------ | :--: |
| Write draft  | ✓    |
| Send it      |      |

Wide tables

A table with many columns is wider than the text. MarkdownPaper lets it run past the text into the page margin and scroll sideways if it still does not fit, so no column gets squashed. Shorter cells help everywhere.

Common problems

• The table shows as plain text. The dash row is missing, or it has a different number of columns from the header row.
• A cell has gone missing. That row has more | than the header, and the extra cells were dropped.
• A cell ends early. There is a | inside it. Write it as \|.

Questions

How do I make a table in Markdown quickly?

Write the header row, then a dash row with --- under each column, then one line per row. Many editors, VS Code with an extension for example, can line the columns up for you.

Can a Markdown table have a list inside a cell?

Not a real list. Write the items with <br> between them, or use bullet characters like • with <br>.

How do I change the width of a column?

Markdown cannot. The app decides column widths from the content. Shorter text gives narrower columns.

Why does my table not show on GitHub?

Check that the dash row is right under the header row, and that it has the same number of columns as the header. If the header has three cells, the dash row needs three groups of dashes.

Next

• Markdown checkboxes and task lists, for lists of things to do.
• Print a Markdown table to PDF with real page margins.