A Markdown table is built from pipes and hyphens: one row for the headers, a divider row of hyphens, then one row per record, with colons in the divider to set alignment. Tables are not part of the original Markdown, but GitHub Flavored Markdown and most modern editors support them. This guide shows how to build, align and fix them.
Key takeaways
- Separate columns with
|and add a divider row of at least three hyphens per column. - Colons in the divider row left-, center- or right-align a column.
- Cells cannot hold block elements such as lists in standard tables.
- Escape a literal pipe inside a cell as
\|.
Basic Markdown Table Syntax
Every table needs a header row and a divider row. The pipes at the very start and end of each line are optional in GitHub Flavored Markdown, but including them makes the source easier to read.
| Tool | Type | Free plan |
| --- | --- | --- |
| Editor A | Desktop | Yes |
| Editor B | Web | Yes |
The divider row must have the same number of cells as the header row, otherwise most parsers will not treat the block as a table at all. You also need a blank line before the table so it is not absorbed into the previous paragraph.
How to Build a Markdown Table Step by Step
- Decide your columns and write the header names between pipes.
- On the next line, add one divider cell of
---for each column. - Add each record as its own line, separating cells with pipes.
- Keep the cell count identical on every line.
- Preview the result and adjust the spacing or alignment as needed.
You do not have to line the pipes up in the source. The renderer ignores extra spaces, so aligning them is only a courtesy to people who read the raw file.

Align Columns With Colons
Place colons on the divider row to control alignment. A colon on the left aligns text to the left, on both sides it centers, and on the right it aligns to the right. Right alignment is the usual choice for numbers.
| Item | Quantity | Price |
|:-----|:--------:|------:|
| Pens | 12 | 4.80 |
| Pads | 6 | 9.00 |
| Divider | Alignment |
|---|---|
:--- |
Left |
:---: |
Center |
---: |
Right |
--- |
Default (usually left) |
Formatting Inside Cells
Inline formatting works within a cell. You can use bold, italics, inline code and links, for example **Done** or [docs](https://example.com). What you cannot do in a standard table is start a new paragraph, a list or a code fence inside a cell. For a line break, many tools accept an inline <br> tag, though this depends on whether the platform allows HTML.
A pipe character is the column separator, so to display one inside a cell you escape it with a backslash. That matters when you document command-line syntax, where pipes are common. See our guide to Markdown code blocks and inline code for how to show such characters safely.

Troubleshooting a Markdown Table
- The table shows as plain text. Check that the divider row exists and that the column counts match, and that a blank line precedes the table.
- A column is missing. A stray pipe in a cell creates an extra column. Escape it.
- The table looks cramped. Markdown has no width or padding controls; styling is up to the site’s stylesheet.
- Merged cells are impossible. Standard syntax has no colspan or rowspan. Use an HTML table if you need them. The MDN reference for the HTML table element covers those attributes.
- Wide tables scroll or wrap awkwardly. Shorten the headers or split the data into two tables.
One last tip on readability: keep each cell short. A markdown table works best for compact facts such as names, dates, numbers and yes-or-no values. Long sentences inside cells make the raw file hard to edit and the rendered table hard to scan, so move longer explanations into the text around it.
Tools That Save Time
Typing pipes by hand gets tedious beyond a few rows. Many Markdown editors include a table helper that inserts a grid and keeps the columns aligned as you type, and some online generators produce the syntax from a spreadsheet-like grid. If your data already lives in a spreadsheet, copying it into such a converter is usually faster than typing it. Our comparison of the best Markdown editors notes which ones help with tables. Feature names and menus change, so check the tool’s own help pages.
Frequently Asked Questions
Is a table part of standard Markdown?
No. It is an extension defined in GitHub Flavored Markdown and supported by many other tools, so a very basic parser may ignore it.
Do I need the outer pipes?
Not in GitHub Flavored Markdown, but include them for readability and for compatibility with stricter parsers.
Can I add a list inside a table cell?
Not with standard syntax. Use line break tags if your platform allows HTML, or move the list outside the table.
How do I center a column?
Put a colon on both sides of the hyphens in that column’s divider cell, like :---:.
Can I make the header row optional?
No. The header row and divider are required, though you can leave the header cells empty if you need a table without visible titles.
Wrap-Up
Headers, a divider row and consistent pipes are the whole recipe. Add colons for alignment, escape stray pipes and preview the page. If the output looks wrong, check your editor’s Markdown flavor first.



