Coffee

Markdown tables without the pain

By Pedro Thomaz, who makes Coffee. 5 min read. Read as Markdown

Checked November 2026 against the GitHub Flavored Markdown spec, GitHub's table docs and the pandoc manual. Coffee isn't affiliated with any of them.

A Markdown table needs only a header row, a row of dashes, and pipes between the columns. Most of the pain comes from two habits: lining the source up by hand, which you don't need to do, and asking a table to hold things it can't.

Tables aren't part of standard CommonMark. The rules most tools follow come from GitHub Flavored Markdown, so that's what this guide describes. If your table starts life in a spreadsheet, see how to paste Excel or Numbers into Markdown instead of typing it.

The smallest table that works

| Name | Role |
| --- | --- |
| Ana | Editor |

That's it. The source doesn't have to line up, as GitHub's docs point out, so this is the same table:

| Name | Role |
|---|---|
| Ana with a long surname | Editor |

Tidy columns are pleasant to read in a plain text editor, but they cost you every time a cell gets longer. Unless other people read the raw file a lot, leave them uneven.

Aligning columns

Alignment goes in the row of dashes. A colon on the left means left, a colon on the right means right, and both mean centre.

| Item | Qty | Note |
| :--- | ---: | :---: |
| Pens | 12 | blue |

Numbers usually read better on the right. Whether an app honours this is up to the app, so check yours if it matters.

Why a table doesn't render

These are the causes worth checking, in the order worth trying them.

No blank line above it. GitHub's docs ask for a blank line before the table. A table straight after a paragraph may not show as one.

The dashes don't match the header. Under the GFM rules, the header and the row of dashes must have the same number of cells, or there's no table at all. Body rows are more forgiving: a short row gets empty cells and extra cells are ignored. Count the header first when a table comes out as plain text.

Too few dashes. The GFM spec only asks for dashes, while GitHub's docs ask for at least three in each column. Three works in both, so use three.

No header. The header can't be left out. Pandoc's manual suggests a header of blank cells if you want a table without one, though not every renderer will draw it neatly.

A pipe in a cell. A | in your text starts a new column.

Putting a pipe in a cell

Write a backslash before it:

| Command | Meaning |
| --- | --- |
| `a \| b` | Send a to b |

The GFM spec needs that backslash even inside inline code, which is easy to forget. Some apps cope without it, so a table can look fine in one app and break in another. The backslash is the portable form.

What a table can't hold

The GFM spec is firm on this: block-level elements can't go in a table. That means no lists, no second paragraph and no code block in a cell. Links, inline code, bold and italics are all fine, according to GitHub's docs.

When your content doesn't fit, these are the usual ways out:

  • Rows with a lot of text: drop the table. A ### heading for each row with a short paragraph under it reads better, especially on a phone.
  • A cell that needs a list: turn the list into a short sentence, or link to a section below the table.
  • A very wide table: split it into two tables that share a first column, or turn it on its side so the columns become rows.
  • Merged cells or real layout: write an HTML table, if your publishing tool allows raw HTML. Pandoc also has its own grid tables, which can hold block elements, but those are pandoc's and won't travel to other tools.
  • Live data: keep the spreadsheet, and link to it.

Changing a table later

Adding a row is easy in any editor. Moving a column isn't, because you have to edit every line. Multi-cursor editing helps if your editor has it. For anything bigger, copy the table into a spreadsheet, rearrange it there and bring it back, which is when the paste guide earns its keep.

In Coffee

Typing / at the start of a line and choosing Table inserts a two-column table. In the page view, Tab moves to the next cell, ⇧Tab moves back, and Tab past the last cell adds a row. Coffee hides the pipes and draws equal-width columns. If a cell is too wide for its column, that row wraps and shows its pipes, so nothing runs out of sight.

Four things are worth knowing, because Coffee is plainer here than the GFM rules:

  • Each row must start with a pipe. GFM lets you leave out the outer pipes, but Coffee shows a table without them as an ordinary paragraph. A table like that still works in other apps.
  • Alignment colons aren't drawn in the page view. Columns there are always aligned left. The colons stay in the file for other tools, and Coffee's PDF and HTML exports follow them.
  • A pipe inside inline code doesn't split the cell in Coffee, with or without the backslash. Keep the backslash for the sake of other apps.

Coffee's calculations skip table rows, so a table won't get answers beside it.

Questions

Do Markdown tables need outer pipes?

Not under GitHub Flavored Markdown or pandoc's pipe tables, where they're optional. They're still worth including, as the GFM spec recommends them for readability and Coffee requires them.

Can a Markdown table have merged cells?

Not in the GFM syntax. Use an HTML table if your publishing tool allows raw HTML, or restructure the content so every row has the same columns.

How do I put a line break in a Markdown table cell?

GFM cells can't hold block elements, so there's no Markdown way to do it. Some renderers accept <br> as raw HTML, but it isn't portable. Coffee shows it as text.

Why do my table's columns not line up in the source?

They don't need to. Spacing in the source has no effect on the result in GFM, so uneven columns are fine.