Markdown Tables: A Complete Guide to Syntax and Formatting

Tables are one of the most useful features in Markdown, but also one of the most misunderstood. The syntax looks simple, but alignment, formatting, and edge cases can trip you up. This guide covers everything you need to know about Markdown tables.

Quick Answer: A Markdown table uses pipe characters (|) to separate columns and hyphens (-) to separate the header row from the body. Add colons to the separator row for alignment: :--- left, :---: center, ---: right. Tables are part of GitHub Flavored Markdown and are supported by GitHub, GitLab, Notion, and all modern Markdown editors.

How Do You Create a Table in Markdown?

A Markdown table uses pipes (|) to separate columns and hyphens (-) to separate the header row from the body.

| Name    | Role      | Location |
| ------- | --------- | -------- |
| Alice   | Engineer  | Berlin   |
| Bob     | Designer  | Tokyo    |
| Carol   | PM        | New York |

The number of hyphens does not matter. A single - per column is enough, but more hyphens make the source more readable.

Column Alignment

Use colons in the separator row to control alignment:

| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| Text         | Text           | Text          |
| More text    | More text      | 123.45        |

• :--- aligns left (default)
• :---: centers the column
• ---: aligns right

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

Formatting Inside Cells

You can use inline Markdown inside table cells:

| Feature       | Status          |
| ------------- | --------------- |
| **Bold text** | `inline code`   |
| *Italic*      | ~~strikethrough~~ |
| [Link](/)     | ==highlighted== |

Block-level elements like lists, code blocks, or headings are not supported inside table cells. If you need complex content, consider using an HTML table instead.

Minimal Syntax

Markdown is forgiving about table formatting. The outer pipes are optional and columns do not need to be aligned in the source:

Name|Role|Location
-|-|-
Alice|Engineer|Berlin
Bob|Designer|Tokyo

This renders identically to the padded version. However, aligned source is easier to read and maintain.

Escaping Pipes

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

| Expression | Result |
| ---------- | ------ |
| `a \| b`   | a or b |

Empty Cells

Leave the space between pipes blank for empty cells:

| A | B | C |
| - | - | - |
| 1 |   | 3 |
|   | 2 |   |

Common Mistakes

Missing separator row. Without the --- row, Markdown will not recognize the table. It will render as plain text.

Mismatched column count. Every row must have the same number of columns as the header. Missing columns will cause rendering issues in some parsers.

Block content in cells. You cannot put multi-line content, lists, or code blocks inside a table cell in standard Markdown. Keep cell content to a single line.

Tables for Documentation

Tables are ideal for:

• API parameter definitions (name, type, required, description)
• Feature comparison matrices
• Configuration option references
• Keyboard shortcut lists
• Status and progress tracking

| Shortcut     | Action         |
| ------------ | -------------- |
| `Ctrl+B`     | Bold           |
| `Ctrl+I`     | Italic         |
| `Ctrl+K`     | Insert link    |
| `Ctrl+Shift+C` | Code block  |

How Do Tables Fit Into Larger Documentation?

Tables are a core part of the Markdown cheat sheet syntax set. They are especially powerful in API documentation, where parameter tables (name, type, required, description) replace long prose explanations with scannable grids. For technical documentation, tables work well for configuration references, compatibility matrices, and version changelogs.

Try It

Open edtr.md and create a table. You can also use the table grid picker in the toolbar to insert a table with the exact number of rows and columns you need.