Markdown tables

A Markdown table is three things: a header row, a divider row made of dashes, and one or more body rows. Cells are separated by pipe characters. The leading and trailing pipes on each line are optional but worth keeping — they make ragged rows obvious at a glance.

Both the header and the divider are mandatory. A table with no divider row is just a paragraph full of pipes, and a table with no header row does not parse at all. If you genuinely want a headerless table, the usual workaround is a header row of empty cells, which renders as a thin blank strip.

The divider needs at least three dashes per column in some parsers, so --- is the safe minimum.

| Region | Units | Revenue |
| --- | --- | --- |
| North | 1,204 | £18,300 |
| South | 980 | £14,110 |

Colons in the divider row set each column's alignment, and nothing else does. A colon on the left of the dashes aligns left, a colon at both ends centres, a colon on the right aligns right. No colon means the renderer's default, which is left in practice.

Align numbers to the right and text to the left; a column of right-aligned figures is far easier to scan. Alignment applies to the whole column including the header cell, and there is no per-cell override — that is a genuine limitation, not a syntax you have not found yet.

| Item | Qty | Unit price |
| :--- | :-: | ---: |
| Cable | 4 | 7.50 |
| Adapter | 12 | 21.00 |

The pipes do not need to line up. Columns are determined entirely by how many pipes separate the cells, so a table typed by hand in a hurry renders identically to one padded into a neat grid. Both tables below produce the same output.

Many editors have a "format table" command that pads the columns for you, and it is worth using — not because the renderer cares, but because a misaligned source table hides the one row that has a missing cell. If you would rather not hand-align anything, build the table in a grid with the table generator and copy the syntax out.

| A | B |
| --- | --- |
| 1 | 2 |

|A|B|
|-|-|
|1|2|

Most inline syntax works inside a cell: bold, italic, strikethrough, inline code, links and images. Block-level syntax does not — you cannot put a heading, a bullet list, a block quote or a fenced code block inside a cell, because the cell ends at the next pipe or newline.

Inline code inside a cell is the usual reason people hit the pipe problem below, since shell commands are full of pipes. Links work exactly as they do elsewhere, and are a good way to keep a table narrow: put a short label in the cell and let the link carry the detail.

| Flag | Meaning | Docs |
| :-- | :-- | :-- |
| `-v` | **Verbose** output | [read](https://example.com/v) |
| `-q` | ~~Quiet~~ (removed) | — |

A literal pipe inside a cell must be escaped with a backslash, \|, or it ends the cell early and pushes the rest of the row into the next column. This bites hardest when documenting shell commands. Escaping works even inside inline code, which is the one place a backslash normally has no effect.

An empty cell is fine: leave nothing between the pipes. A row with fewer cells than the header gets padded with blanks; a row with more has the extras silently dropped, which is why a table can quietly lose data. Count your pipes when a column looks wrong.

| Command | Notes |
| :-- | :-- |
| `ls \| wc -l` | Counts files |
| `pwd` |  |

There are no merged cells — no colspan, no rowspan. There are no multi-line cells: a cell is one line of text, so a paragraph with a line break inside it is not possible in standard syntax. There is no column width control, no cell background, no nested table, and no caption.

The workarounds, in order of how well they travel. Repeat the value down a column instead of merging, and rely on sorting for the visual grouping. Replace an intended line break with a separator such as a semicolon or a middle dot. Move genuinely long content out of the table into a section below, and link to it from the cell. On GitHub you can use a raw <br> inside a cell for a line break — but raw HTML is disabled in this viewer, so it would show as text here.

Work down this list; it is almost always one of these.

• No blank line above the table. If a paragraph sits directly on top of the header row, the whole table is absorbed into that paragraph. This is the most common cause by far.
• The divider row is missing or malformed. It needs dashes, and the same number of columns as the header.
• The column counts disagree. Header, divider and body rows must all have the same number of cells.
• An unescaped pipe inside a cell has split the row.
• The renderer has no table support. Tables are a GitHub Flavored Markdown extension; they work here and on GitHub, but not in Slack, Discord, or a strict CommonMark parser.
• The table is indented four spaces, which makes it a code block.

Results below.

| Test | Status |
| :-- | :-- |
| Unit | Pass |

A rendered table copies cleanly. Open the document in a viewer, select the rendered table rather than the source, and paste into Word or Google Docs — you get a real table object with the alignment preserved. Pasting the raw Markdown instead gives you a block of pipes.

For a whole document, Markdown to Word converts tables into native Word tables in a .docx file, which is the reliable route when the document has several of them. Going the other way, pasting a spreadsheet range into a Markdown file gives you tab-separated text, not a table; run it through the table generator to get the pipes.