Markdown table syntax
A GitHub Flavored Markdown table has three parts: a header row, a separator row made of dashes, and any number of body rows. Pipes | separate the cells. The outer pipes are optional and the columns don’t have to line up in the source, but aligned columns are much easier to read and edit, which is what “Align columns” does.
| Name | Role | Joined |
| :---- | :------: | -----: |
| Ana | Designer | 2021 |
| Kofi | Engineer | 2024 |How the colons control alignment
The separator row does double duty: it tells the parser “the line above is a header” and, with colons, sets each column’s alignment. Pick an option and watch both the source and the rendered column change.
| Price | | :----: | | $4 | | $12.50 | | $1,299 |
| Price |
|---|
| $4 |
| $12.50 |
| $1,299 |
:---: colons on both ends: centred. Good for short status values like ✅ or Yes/No; hard to scan for long text.
Table tips and limits
- Line breaks in a cell: use
<br>; each row must stay on one line. - Pipes in a cell: escape as
\|, including inside inline code. - Formatting in cells: bold, italic, links, inline code and images all work. Lists, headings and code blocks don’t.
- No merged cells or captions: GFM tables can’t span rows or columns. Use HTML if you must.
- Wide tables scroll horizontally on GitHub. Consider transposing (swap rows and columns) if you have many columns and few rows.
- Tables need a header row. For a header-less look, leave the header cells empty.
Have a spreadsheet export? Use the CSV to Markdown table converter. Need to tidy tables that are already in a document? The formatter aligns every table at once.