Markdown Tables: Syntax, Alignment, and the Ways They Break

Markdown tables are five minutes to learn and five years of small surprises. The delimiter row has rules nobody told you about, colons count toward column width, cells can't do things you'll want them to do, and the difference between a table that renders and one that becomes plain text is usually one character. Here's the syntax with the traps marked.

The anatomy, in five lines

Every GFM table is the same skeleton:

• Header row — plain cells separated by pipes.
• Delimiter row — the second line, one cell per column, each at least three dashes. This row is what makes it a table; remove it and you have prose with punctuation.
• Data rows — as many as you like, same pipe separation.
• Pipes — required between cells; the leading and trailing ones are conventionally included (GFM says optional, practice says include them).
• A blank line before the table — without it, the previous paragraph swallows the header.

A delimiter row matches the column widths around it when you generate tables mechanically. Hand-written ones usually just use | --- | everywhere, which is fine — the dash count doesn't change rendering, only how the source reads.

Alignment: the colon rules

Two details worth internalizing. First, the colons count toward the cell's width — a centered delimiter for a six-character column is :----:, six characters of which two are colons. Second, alignment is per column only. There is no per-cell alignment in markdown tables, and no rowspan or colspan either; if your data needs those, it needs HTML.

Padding: optional for machines, mandatory for readers

Renderers ignore the spaces inside cells, which means |a|b| and a fully padded table produce identical HTML. But source is for people too. A padded table lets you scan a column vertically, and a single-cell edit produces a one-line diff instead of a reflowed block. The engine behind our markdown table generator pads every cell to the widest value in its column plus one space each side — measured on a 3-column, 4-row monitoring grid, that's a 249-byte table where every pipe lines up and the longest cell ("ToolAspect embeds", 17 characters) sets column one to 19.

The counter-argument: editing a wide cell reflows the whole column, so a team reviewing dense diffs may prefer unpadded tables and a formatter in CI. Both survive; pick one and stay consistent.

What breaks tables

1. An unescaped pipe — | yes|no | splits into two cells. Escape it: yes\|no.
2. A blank line between header and delimiter row — the table stops being a table. Same for a blank line inside what you meant as one table; you get two.
3. A short delimiter row — every column needs its delimiter cell. GFM is forgiving about dash counts, not about missing cells.
4. Multi-line cells — there's no such thing. A newline ends the row. If your CSV has embedded newlines in quoted fields, join them before converting.
5. Renderer support — tables aren't in original markdown at all; they're a GFM extension. Most platforms have them; strict CommonMark setups don't unless an extension is on.

From CSV and spreadsheets

The tedious version of table-making is retyping spreadsheet data with pipes. The fast version: copy the range from Excel or Google Sheets (that puts tab-separated values on your clipboard) or export CSV, and paste it into the generator. It detects the delimiter, handles quoted fields with embedded commas, escapes pipes, pads the columns, and hands you the markdown.

Numbers benefit most: set the numeric columns to right-align and the decimal points line up, which is the whole reason financial tables have been right-aligned since ledgers were paper. For data that's headed to an API rather than a README, the CSV to JSON converter is the better pipeline — JSON doesn't care about pipes, padding, or line breaks.

When tables aren't the answer

Markdown tables cap out fast: no merged cells, no per-cell styling, no column widths, no sorting. Comparison matrices with three short columns are their sweet spot. Anything you find yourself squinting at — eight columns, cells with lists inside them — will read worse as a table than as headed subsections. And when the document's destination is Word or PDF rather than a repo, convert at the document level instead: the markdown to PDF and markdown to Word tools carry tables over as real table layouts, not pipe text.

The bottom line

Learn the delimiter row, respect the colon rules, escape your pipes, and pad your cells — that's 95% of markdown table craft. The remaining 5% is knowing the format's ceiling and choosing headings-and-lists when you hit it. Generate the mechanical parts with a tool and spend your attention on whether the table should exist at all.

Frequently Asked Questions

Related Tools