Markdown Tables: The Complete Guide With Examples

Markdown tables are one of the most-used — and most-mistyped — features in GitHub Flavored Markdown. This covers everything from basics to edge cases.

Basic Syntax

A markdown table has three parts: header row, separator row, data rows.

markdown
| Name    | Age | City     |
|---------|-----|----------|
| Alice   | 28  | New York |
| Bob     | 34  | London   |

Rules:

• At least 3 dashes per column in the separator row
• Pipes (|) required around each cell
• Spaces around cell content are optional but improve readability

Alignment

markdown
| Left        |    Center    |     Right |
|:------------|:------------:|----------:|
| Text        |     Text     |      Text |

• :--- → left (default)
• :---: → center
• ---: → right

Right-align numbers so decimal points line up. Center status values.

Minimum Valid Table

markdown
|Col1|Col2|
|---|---|
|A|B|

Most editors auto-pad when you save.

Content Inside Cells

Escaping Pipes

markdown
| Expression | Meaning |
|------------|---------|
| `a \| b`  | Logical OR |

Or use the HTML entity |.

Table Limitations

• No row/column spans — can't merge cells
• No multi-line cells — each cell is one line
• No nested tables
• No captions
• No footer rows

When you hit these limits, use HTML.

Common Patterns

API Endpoint Reference

markdown
| Method | Endpoint     | Auth   | Rate Limit |
|--------|-------------|--------|-----------|
| GET    | /api/users  | Bearer | 100/min    |
| POST   | /api/users  | Bearer | 20/min     |

Feature Comparison

markdown
| Feature     | Free | Pro | Enterprise |
|-------------|------|-----|------------|
| Projects    | 3    | ∞   | ∞          |
| Storage     | 1 GB | 20 GB | Custom   |
| SSO         | ❌   | ❌  | ✅         |

Parameter Reference

markdown
| Parameter | Type    | Required | Default | Description        |
|-----------|---------|----------|---------|--------------------|
| limit     | integer | No       | 20      | Results per page   |
| offset    | integer | No       | 0       | Results to skip    |

Quick Reference

Practice building tables in MarkGenie's live editor — you'll see results instantly.