Markdown tables: syntax, alignment and the gotchas
Tables are not part of the original Markdown. They come from GitHub Flavored Markdown (GFM), and today GitHub, GitLab, Obsidian, VS Code previews and most static site generators render them the same way.
The minimal table
A table is a header row, a delimiter row and any number of body rows. Cells are separated by pipes (|). The delimiter row is what turns plain text into a table: without it the lines stay a paragraph.
| Name | Role | Score |
| ----- | ------- | ----- |
| Ada | Lead | 92 |
| Grace | Analyst | 88 |
Rules the parser actually checks
- The delimiter row must have the same number of cells as the header row, otherwise the block is not a table.
- Each delimiter cell needs at least one hyphen; three are a readability habit, not a requirement.
- Leading and trailing pipes are optional, but writing them keeps single-column tables unambiguous.
- Columns do not have to line up in the source — padding with spaces is only for people reading the raw text.
- A body row with fewer cells gets empty cells; extra cells beyond the header are dropped.
- The table ends at the first blank line or at a line that starts another block, such as a heading.
Column alignment
Alignment is set with colons in the delimiter row: a colon on the left aligns left, on both sides centres, on the right aligns right. Without colons the renderer uses its default, which is usually left.
| Item | Qty | Price |
| :------ | :-: | ----: |
| Coffee | 2 | 3.50 |
| Bagel | 1 | 2.25 |
Pipes, line breaks and formatting inside cells
- A literal pipe inside a cell must be escaped as
\|— this applies inside inline code too, because the table is split into cells before code spans are parsed. - Inline formatting works in cells: bold, italic,
codeand links. - Block content does not: no lists, headings or fenced code inside a cell. For a line break, GitHub accepts an HTML
<br>; plain Markdown renderers may not. - There is no colspan or rowspan. If you need merged cells, write an HTML table instead.
Turning spreadsheet data into a table
Copying cells from Excel or Google Sheets gives you tab-separated text. Converting it by hand means adding pipes to every row, writing the delimiter row and escaping any pipes in the data. That is the part worth automating: a generator does the pipes, alignment colons and escaping, and you only check the result.
Questions
- Do Markdown tables need a header row?
- Yes. GFM requires a header row followed by the delimiter row. If your data has no natural header, put short column labels there.
- Why does my table show up as plain text?
- Usually the delimiter row is missing, has a different number of cells than the header, or there is no blank line between the table and the paragraph above it.
- Can I merge cells in a Markdown table?
- No. Markdown tables have no colspan or rowspan. Use an HTML table when you need merged cells.
Skip the manual part
Fill the grid or paste csv rows: a markdown table generator that aligns every column and copies the table in markdown syntax.
See Markdown Table Generator Add to Chrome — free