Web & APIs · 3 min read
Markdown Tables: Syntax, Alignment, and Limits
Tables are not part of the original Markdown, but the GitHub-flavoured extension is now supported almost everywhere — GitHub, GitLab, VS Code, Notion, Obsidian, and most static site generators.
Try it yourself with the related tool.
Build a Markdown table →Advertisement
The basic syntax
Write a header row with cells separated by pipes, then a delimiter row of dashes, then data rows: | Name | Role |, | --- | --- |, | Ana | Admin |. The outer pipes are optional, and the columns do not need to line up in the source — renderers only care about the pipes.
Alignment
Colons in the delimiter row set alignment: :--- for left, :---: for centre, and ---: for right. Right-align numeric columns so digits line up.
Escaping and formatting inside cells
Inline formatting works inside cells — bold, links, and code. A literal pipe must be escaped as \|. There is no syntax for line breaks inside a cell, though most renderers accept <br>.
When to stop using a Markdown table
Markdown tables cannot merge cells, hold lists or code blocks, or set column widths. When a table needs those, or has more than a handful of columns, an HTML table or a linked CSV file is easier to maintain.