Markdown Tables: The Complete Guide

A Markdown table consists of three parts: a header row, a separator row, and data rows. Columns are separated by pipe characters (|).

| Name     | Role       | Location |
|----------|------------|----------|
| Alice    | Developer  | NYC      |
| Bob      | Designer   | London   |
| Charlie  | PM         | Tokyo    |

This renders as a clean three-column table. A few rules to remember:

• The header row defines column names and is always required.
• The separator row (dashes between pipes) is required — it tells the parser this is a table.
• You need at least three dashes (---) per column in the separator.
• Leading and trailing pipes are optional but recommended for readability.
• Columns don't need to be perfectly aligned in the source — the renderer handles it.

You can control text alignment within columns using colons in the separator row:

| Left     | Center     | Right    |
|:---------|:----------:|---------:|
| text     | text       | text     |
| aligned  | aligned    | aligned  |
| left     | center     | right    |

• :--- — Left-aligned (default)
• :---: — Center-aligned
• ---: — Right-aligned

Right alignment is particularly useful for numeric data like prices, counts, or percentages.

You can use most inline Markdown formatting inside table cells:

• Bold: **bold text**
• Italic: *italic text*
• Inline code: `code`
• Links: [text](url)
• Images: ![alt](url) (though images in tables can be awkward)
• Strikethrough: ~~deleted~~

| Feature    | Status          | Notes                     |
|------------|-----------------|---------------------------|
| **Auth**   | ✅ Complete      | Shipped v2.1              |
| *Search*   | 🚧 In Progress  | [Tracking issue](#)       |
| ~~Cache~~  | ❌ Removed       | Replaced with `Redis`    |

If your cell content contains a literal pipe character, escape it with a backslash:

| Expression    | Result |
|---------------|--------|
| true \| false | true   |

Without the backslash, the parser would interpret the pipe as a column separator and break your table layout.

Markdown tables are intentionally simple, which means they have real limitations:

• No merged cells — No rowspan or colspan. Every cell is independent.
• No multi-line cells — Each row must be a single line. You can't have paragraphs or lists inside cells.
• No cell styling — No background colors, borders, or custom widths.
• No nested tables — You can't put a table inside a table.
• No caption — There's no native way to add a table title or caption.

When Markdown tables aren't enough, you have several options:

HTML Tables

Most Markdown renderers accept inline HTML. For complex layouts, write an HTML table directly in your Markdown file. You get full control over colspan, rowspan, styling, and structure — but lose the readability advantage of Markdown.

Export to Spreadsheets

For data-heavy tables, consider writing your content in Markdown and exporting the table data to Excel or a spreadsheet format. Tools like MarkdownFTW can export your Markdown directly to Excel (.xlsx) and PowerPoint (.pptx), which handle complex table layouts natively.

Table Generator Tools

Online table generators let you build tables visually and output Markdown syntax. These are especially useful for wide tables where typing pipes by hand gets tedious. You paste the generated Markdown into your document and move on.

• Align your pipes — It's not required, but aligned columns make the raw Markdown much easier to read and edit.
• Keep cells short — If a cell needs more than ~40 characters, consider restructuring your data or using a different format.
• Use consistent spacing — One space of padding inside each cell is standard.
• Add a blank line before and after — Some parsers require it; all parsers handle it correctly.

For a complete reference of all Markdown syntax including tables, check out our Markdown syntax guide.