Tablizer

Markdown Tables: Syntax, Alignment, and Common Mistakes

Last updated 19 August 2026 · about 4 minutes to read

How Markdown table syntax works, how alignment is set with colons, what breaks a table, and the limits you cannot work around.

Markdown tables are pipes between cells and a dashed rule under the header. The syntax is small enough to learn in a minute and has four ways to go wrong that account for nearly every broken table.

The minimum that works
| Name   | Role     | Hours |
| ------ | -------- | ----- |
| Halima | Analyst  | 38.5  |
| Wei    | Manager  | 40    |

The rule row is not optional

The line of dashes is what makes those lines a table rather than three lines of text with pipes in them. Leave it out and every renderer shows the pipes literally.

The number of dashes does not matter, and neither does the padding. Three dashes is the conventional minimum because fewer looks like a mistake.

Alignment is set with colons

Left, centre, right
| Left | Centre | Right |
| :--- | :----: | ----: |
| a    |   b    |     c |

A colon on the left aligns left, which is also the default. On the right aligns right, which is what numeric columns want. On both centres. There is no way to set alignment per cell, only per column.

The four things that break a table

  • A pipe inside a value. It ends the cell. Escape it with a backslash: a\|b stays one cell.
  • A line break inside a value. The row ends at the newline. Use a <br> tag, which every common renderer passes through to the HTML.
  • A blank line in the middle. It ends the table. Everything after it is a new block.
  • Inconsistent column counts. A row with more cells than the header has the extras dropped; one with fewer gets empty cells. Neither is an error, which is why it goes unnoticed.

What Markdown tables cannot do

No merged cells, no nested tables, no multi-line cells, no column widths, no captions. If you need any of those, write HTML instead. A Markdown document can contain raw HTML, and every renderer that supports tables also passes HTML through.

Tables are not in the original Markdown specification. They come from GitHub Flavored Markdown, which is why they work on GitHub, GitLab, Obsidian, Notion and most static site generators, and not in every renderer that calls itself Markdown.

Padding

Renderers ignore the padding entirely, so a table that lines up in the source and one that does not produce identical output. The padding is for whoever opens the raw file next, which on a README is a lot of people. It is worth the bytes.

Tools mentioned here

Questions

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

Use a <br> tag. The row ends at the newline, so there is no Markdown syntax for it. Every renderer that supports tables also passes raw HTML through.

Can I have a table without a header row?

Not in standard Markdown table syntax. The header row and the rule under it are both required. Leave the header cells empty if you have no labels, or use an HTML table instead.

More guides