Markdown cheatsheet · Tables
Markdown tables
Pipes (|) separate columns, and a row of dashes separates the header from the body. That second row is mandatory: it's what makes it a table.
The syntax
| Name | Role | | ----- | -------- | | Ada | Engineer | | Grace | Admiral |
| Name | Role |
|---|---|
| Ada | Engineer |
| Grace | Admiral |
The columns don't need to line up in the raw text; ragged pipes render the same table. Aligning them is purely for your own reading comfort. The outer pipes are optional too.
Column alignment
Colons in the dash row set the alignment: left (:---), center (:---:), or right (---:). Right alignment is what you want for numbers.
| Item | Qty | Price | | :---- | :-: | ----: | | Pens | 3 | 4.50 | | Paper | 10 | 12.00 |
| Item | Qty | Price |
|---|---|---|
| Pens | 3 | 4.50 |
| Paper | 10 | 12.00 |
Formatting inside cells
Inline elements work in cells: bold, italic, code, links, images. Block elements don't: no lists, no headings, no code blocks inside a table cell.
| Command | Effect | | -------- | --------------- | | `Cmd+P` | **Open** a note | | `Cmd+E` | *Source* mode |
| Command | Effect |
|---|---|
Cmd+P | Open a note |
Cmd+E | Source mode |
The two classic problems
A pipe inside a cell
A literal | in cell text would start a new column. Escape it as \| (inside code spans in a table, use | if the backslash doesn't take).
Multiple lines in one cell
Table rows must stay on one line of markdown. To show a visual line break inside a cell, use the HTML tag <br>: | first line<br>second line |. If a cell needs a real paragraph or list, that's usually the sign the content wants to be a section, not a table.
A checkbox in a cell
Task-list syntax (- [ ]) only works inside a list, so it won't render in a table cell. To get the look, use the emoji ✅ / ⬜, which travels everywhere but isn't clickable. The checkboxes guide covers this in full.
Common questions
Can I make a table without a header?
Not in GFM; the dash row is required and the row above it becomes the header. A common workaround is a header of empty cells: | | | above the dashes.
Can I merge cells across columns or rows?
No, markdown tables have no colspan or rowspan; every row has the same number of cells and there's no syntax to join them. The only route is to drop the whole table to an HTML <table> with colspan/rowspan attributes, which GitHub and most renderers accept but which you then maintain by hand. If you're reaching for merged cells, it's often a sign the data wants two tables, or a list.