Markdown tables: the complete reference

Everything about GFM (GitHub-flavored) pipe tables — anatomy, alignment, escaping, the mistakes that break rendering, and moving tables between tools.

Basic syntax

| Column A | Column B |
|----------|----------|
| cell 1   | cell 2   |
| cell 3   | cell 4   |

Three parts: a header row, a divider row (hyphens at minimum), then body rows. The divider must exist — without it the text is a paragraph, not a table. Spacing in the source doesn't need to align; pipes matter, not columns. Leading and trailing pipes are optional but recommended for portability.

Alignment

Colons in the divider set column alignment — :--- left (the default), :---: center, ---: right:

| Left | Center | Right |
|:-----|:------:|------:|
| a    | b      | c     |

Alignment is the only cell-level control GFM offers: no cell background, no merged cells, no column spanning.

Inline formatting inside cells

Cells accept inline Markdown — bold, italic, inline code and [links](https://example.com) — but not block elements: no lists, headings or nested tables inside a cell. Each row is one source line; long line breaks need an explicit <br>.

Common mistakes that break tables

No blank line before the table — tight against a paragraph, most parsers treat the pipes as text.
Malformed divider row — it must contain only hyphens, colons and pipes, with exactly as many cells as the header row.
Unescaped pipe inside a cell — a literal | splits the cell and shifts every column after it. Escape as \|.
Ragged rows — GitHub tolerates missing trailing cells (rendering them empty), but some parsers and converters flag or pad them, so keep row lengths consistent.
Indented tables — four leading spaces turn the whole block into a code fence.

Paste a suspect table into the table generator — it re-normalizes alignment and escaping into the canonical form.

Moving tables in and out of other tools

Direction	Tool	Notes
Excel / Sheets → Markdown	Excel to Markdown	Cached values only; leading zeros preserved as text
CSV / TSV → Markdown	CSV to Markdown	Full RFC-4180: quoted fields, embedded commas, multiline cells
Markdown → Excel / CSV	Markdown Table to Excel	Every table detected; values written as text, never coerced
Markdown → JSON	Markdown to JSON	Header row becomes keys; type inference with an off switch
Build or reformat one	Table Generator	Paste cells or an existing table; alignment and escaping normalized

All five run in your browser with no upload — and the format support matrix documents how each exporter handles table alignment, multi-line cells and escaping.

Tables in GitHub, Reddit and Slack

GitHub renders full GFM including alignment and inline formatting; keep a blank line between the table and surrounding text.
Reddit supports pipe tables in most contexts (alignment included) but not inside quotes.
Slack and Discord don't render tables — the pipes display literally. For chat, the Markdown → image tool renders the table as a shareable picture.

Frequently asked questions

How do I write a line break inside a Markdown table cell?

Use an HTML <br> tag — Markdown's two-space line-break rule does not work inside a table row, because the row is one long line. Most renderers, including GitHub, accept <br> inside table cells.

Does Markdown support merged cells?

No. GFM tables have no colspan or rowspan. To show merged data, repeat the value in each row or restructure the table; some preprocessors generate repeated cells from spanning source data.

Why is my Markdown table not rendering?

The three usual causes: no blank line separating the table from the preceding paragraph, a malformed alignment row (it must be pipes, dashes and colons only, on its own line), or unescaped pipes inside cells splitting rows prematurely.

How many columns can a Markdown table have?

The format sets no limit — readability does. Beyond roughly seven columns, rows become hard to scan in source form and often overflow the rendered page width; consider transposing the table or splitting it.

Do Markdown tables appear correctly in Word and Excel?

Not by pasting — Word and Excel have no Markdown parser. Convert first: a structure-aware converter turns GFM tables into editable Word tables or real .xlsx sheets, preserving header rows, alignment and leading zeros.