How to make a table in Markdown
Try it — edit the markdown and watch the preview
Result
Runs entirely in this tab. Open the full editor to work on a real document.
A Markdown table is pipes for the cells and a row of dashes to mark the header:
| Element | Syntax |
| --- | --- |
| Heading | # Title |
| Bold | **text** |
The separator row is what makes it a table. Without it, the pipes are just characters in a paragraph.
The pipes do not need to line up
These two render identically:
| Element | Syntax |
| --- | --- |
| Heading | # Title |
| Element | Syntax |
| -------- | ------- |
| Heading | # Title |
Padding is for the human reading the source, not the parser. Aligned columns are much easier to edit by hand, which is why most people pad them anyway.
Alignment
Colons in the separator row set each column’s alignment:
| Separator | Alignment |
|---|---|
:--- | left |
:---: | centre |
---: | right |
Right-aligning numeric columns makes them far easier to compare down the page.
Two things that need escaping
Line breaks inside a cell need <br>. Trailing spaces and backslashes do
not work, because the cell is parsed before line-break rules apply.
A literal pipe needs \|, otherwise it is read as a cell boundary. This
bites when documenting shell commands — a \| b inside a cell.
Tables are a GFM extension
Tables are not in original Markdown; they come from GitHub Flavored Markdown. Support is effectively universal today, but a strict CommonMark parser with no extensions will render the pipes as plain text.
Common questions
- What is the basic table syntax?
- Pipes separate the cells and a row of dashes under the header marks it as a table. The separator row is required — without it the pipes render as literal characters in a paragraph.
- Do the pipes need to line up?
- No. Ragged columns render identically to neatly padded ones, because the pipes alone define the cell boundaries. Padding is purely for whoever reads the raw file.
- How do I align a column?
- Add colons to the separator row. :--- is left, :---: is centre and ---: is right. Alignment is per column and applies to the whole column including the header cell.
- How do I put a line break inside a cell?
- Write <br> in the cell. Trailing spaces and backslashes do not work there, because the cell is parsed before line-break rules apply. This is the one place inline HTML is hard to avoid.
- How do I put a literal pipe character in a cell?
- Escape it as \| so it is not read as a cell boundary. Inside inline code spans it still needs escaping, which surprises people writing about shell pipelines.
- Are tables part of standard Markdown?
- No — they come from GitHub Flavored Markdown. Support is near-universal now, including GitHub, GitLab and most static site generators, but a strict original-Markdown parser will pass the pipes through as plain text.