Markdown Table Syntax: Alignment, Escaping and Line Breaks
Write a Markdown table with pipes and hyphens, align columns with colons, escape pipes inside cells, add line breaks, and learn what tables cannot do.
Updated
A Markdown table is built from pipes and hyphens: a header row, a delimiter row of hyphens, then one line per data row, with | between cells. Colons in the delimiter row set column alignment. Tables are an extension from GitHub Flavored Markdown, not part of original Markdown, so they work on GitHub and most modern editors but not in every parser.
Basic syntax
Here is the source of a three-column table. Each line of the source is one row of the table.
| Name | Role | City || ----- | -------- | ------ || Ada | Engineer | London || Grace | Admiral | NYC |
It renders like this:
| Name | Role | City |
|---|---|---|
| Ada | Engineer | London |
| Grace | Admiral | NYC |
The rules, as defined in the GitHub Flavored Markdown (GFM) specification:
- The first line is the header row. A table cannot be written without one.
- The second line is the delimiter row. Each cell contains only hyphens, with optional colons for alignment. Three hyphens per column is the convention and the safest choice across parsers.
- The header row and the delimiter row must have the same number of cells, or the block is not treated as a table.
- Every following line is a data row, until a blank line or another block element ends the table.
- Spaces around cell content are ignored, so the pipes do not have to line up. Padding the columns just makes the source easier to read.
Put a blank line before the table. Some parsers will not recognize a table that directly follows a paragraph.
Leading and trailing pipes
GFM treats the pipes at the start and end of each row as optional, so this is also a table on GitHub:
Name | Role--- | ---Ada | Engineer
Keep the outer pipes anyway. They are recommended by the specification, they make single-column tables possible, and simpler parsers require them.
Column alignment
Alignment is set per column with colons in the delimiter row.
| Delimiter cell | Alignment |
|---|---|
--- | Default, usually left |
:--- | Left |
:---: | Center |
---: | Right |
A table with a left-aligned label, a centered status and a right-aligned amount looks like this in the source:
| Item | Status | Price || :----- | :----: | ----: || Coffee | In | 3.50 || Tea | Out | 12.00 |
Right-align columns of numbers so the digits line up. Alignment applies to the whole column, header included; there is no way to align a single cell.
Formatting inside cells
Cells accept inline Markdown: bold, italic, inline code, links and images all work. Block elements do not. You cannot put a heading, a list, a blockquote or a fenced code block inside a cell.
Escaping pipes
Because the pipe separates cells, a literal pipe in your content has to be escaped with a backslash: write \|. This matters most in tables that document shell commands, regular expressions or TypeScript union types.
In GFM the escape is needed even inside inline code. A code span containing a \| b in a table cell is displayed as a, pipe, b with the backslash removed. Outside tables that same backslash would be shown literally, which is a common source of confusion when moving text into and out of a table.
Where the renderer allows HTML, the entity | is an alternative that also produces a pipe character in normal text.
Line breaks in cells
A table row must be one line of source, so pressing Enter inside a cell ends the row. For a visible line break within a cell, use the HTML tag <br>:
| Step | Details || --- | --- || 1 | Install the package<br>Restart the server |
This works on GitHub and in most renderers that pass HTML through. It does not work where HTML is stripped or escaped, including some chat apps and comment systems. In those places, split the content into two rows or move the detail below the table.
What Markdown tables cannot do
The syntax is deliberately small. It has no way to express:
- Merged cells, meaning column spans or row spans
- Tables without a header row
- Multi-line source for a single cell
- Lists, code blocks or multiple paragraphs inside a cell
- Column widths, borders, colors or captions
- Row headers, where the first cell of each row is a header
For any of these, write an HTML table element instead. GitHub and many other renderers accept raw HTML in Markdown files. Some writers imitate a headerless table by leaving every header cell empty; it renders, but an empty header row is announced as such by screen readers.
Rows are forgiving in one respect. In GFM, a data row with fewer cells than the header is padded with empty cells, and extra cells beyond the header count are ignored.
Where tables work
Tables were introduced by PHP Markdown Extra and adopted by GFM. They are not in the CommonMark core specification, so support depends on the tool. GitHub, GitLab, most static site generators, documentation tools and note apps render them. Plain CommonMark parsers with no extensions enabled show the pipes and hyphens as ordinary text.
The rest of the syntax, from headings to task lists, is in the Markdown cheat sheet.
Practical tips
- Keep tables narrow. Wide tables force horizontal scrolling on phones; four or five columns is a comfortable limit for prose.
- Keep cells short. If a cell needs a paragraph, the content probably belongs in a list or under its own heading.
- Do not align the source by hand in large tables. Editors such as VS Code have formatters that pad the columns for you.
- After editing, compare the row count in the rendered table with your source. A missing pipe usually shows up as a short row or a shifted column.
Previewing a table
Paste a table into the Markdown Preview to see it rendered next to the source as you type. To get the HTML for it, the Markdown to HTML converter outputs the table, thead and tbody markup, ready to copy.
Both tools render basic pipe tables, and bold, italic, inline code and links work inside cells. Their table support is simpler than GitHub's, so note the differences:
- Every row must start and end with a pipe. Rows without outer pipes are shown as plain text.
- Colons in the delimiter row are accepted, but alignment is not applied to the output.
- An escaped pipe is not recognized and splits the cell in two.
- A
<br>tag is displayed as text, not as a line break. - Short rows are not padded with empty cells.
That makes them a good fit for checking structure, such as whether every row has the right number of cells. For alignment, escapes and line breaks, confirm the result on the platform where the table will be published.
Try it
Open the Markdown Preview, type a header row, a delimiter row and a few data rows with a pipe at each end, and watch the table render. Then paste the same source into the Markdown to HTML converter to copy clean table markup.