Markdown table syntax in one minute
A markdown table is a header row, a separator row, and any number of body rows. Pipes split the cells, and the separator row of dashes tells the renderer where the header ends.
| Name | Role | Start date |
| :---- | :------: | ---------: |
| Ada | Engineer | 2026-01-12 |
| Grace | Designer | 2026-02-03 |
Column alignment
Colons in the separator row set the alignment for the whole column:
:---or---is left aligned (the default):---:is centered---:is right aligned
The alignment buttons above each column in the generator write these colons for you.
Pipes inside a cell
A literal | inside a cell would start a new column, so escape it as \|. The generator does this automatically whenever a cell contains a pipe. Line breaks inside a cell are not part of the syntax; use <br> where the renderer allows inline HTML.
Padded or compact
Renderers ignore extra spaces, so | a | b | and | a | b | produce the same table. Padded output lines the columns up so the source is readable in a code review; compact output is shorter and easier to paste into a chat or a commit message. The "Align columns" switch flips between the two.
What GitHub Flavored Markdown supports
Tables are a GFM extension, not part of the original Markdown or CommonMark. GitHub, GitLab, Bitbucket, Obsidian, Notion, Discord's code preview, VS Code, and most static site generators render them. Inside cells you can use inline formatting such as **bold**, *italic*, `code`, links, and images. You cannot nest lists, headings, code blocks, or another table inside a cell, and cells cannot span rows or columns.
Every table needs a header row and a separator row with at least three dashes per column. If a row has fewer cells than the header, the missing cells render empty; if it has more, the extras are dropped.
When a markdown table doesn't render
It shows up as lines of pipes
Check three things. The table needs a blank line above it, or the renderer reads it as part of the paragraph before. The separator row of dashes must be there, directly under the header. And the platform has to support GFM tables: GitHub, GitLab, Obsidian and most docs tools do, but some comment boxes and chat apps don't.
A column split in two
An unescaped | inside a cell starts a new column. The generator escapes pipes for you; when you edit the markdown by hand, write \| instead, even inside inline code.
I need merged cells or several paragraphs in a cell
Pipe tables can't do either. Where the renderer allows HTML (GitHub does), write the table as an HTML <table> with colspan or rowspan, or split the content into two simpler tables.
Other ways to make a markdown table
- Write it by hand. For two or three rows, typing pipes and dashes is quick, and the columns don't need to line up.
- Your editor. VS Code extensions such as Markdown All in One reformat a table's columns when you format the document, and Obsidian has table editing built in.
- Other online generators. TablesGenerator.com offers a spreadsheet-style editor, and TableConvert converts between dozens of table formats.
- From a file. For a whole spreadsheet or CSV file, the Excel to Markdown and CSV to Markdown converters skip the grid entirely. Pandoc does the same on the command line with
pandoc -f csv -t gfm data.csv.