Markdown Tables: Complete Guide with Examples

Tables are one of the most useful — and most frustrating — features in Markdown. Getting the syntax right can be tricky, especially for complex data. This guide covers everything from basic tables to advanced formatting techniques.

Basic Table Syntax

A Markdown table consists of three parts:

1. Header row — column names
2. Separator row — dashes separating header from data
3. Data rows — your content

| Name    | Role       | Department |
|---------|------------|------------|
| Alice   | Developer  | Engineering|
| Bob     | Designer   | Product    |
| Charlie | Manager    | Operations |

Renders as:

Rules

• Use | (pipe) to separate columns
• Use - (dashes) in the separator row (minimum 3)
• The header row is required
• Leading and trailing pipes are optional but recommended for readability

Column Alignment

Control text alignment with colons in the separator row:

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         |         Right |
| Text         | Text           |          Text |
| More         | More           |          More |

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

When to Use Each Alignment

Formatting Inside Tables

You can use inline Markdown inside table cells:

| Feature | Syntax | Rendered |
|---------|--------|----------|
| Bold | `**bold**` | **bold** |
| Italic | `*italic*` | *italic* |
| Code | `` `code` `` | `code` |
| Link | `[text](url)` | link |
| Strikethrough | `~~text~~` | ~~text~~ |

What You Can NOT Use in Table Cells

• Block elements: headings, blockquotes, code blocks
• Multiple paragraphs
• Lists (unless using HTML)
• Images wider than the cell

Practical Table Examples

Feature Comparison Table

| Feature        | Free Plan | Pro Plan | Enterprise |
|:---------------|:---------:|:--------:|:----------:|
| Users          | 5         | 50       | Unlimited  |
| Storage        | 1 GB      | 100 GB   | 1 TB       |
| API Access     | ❌        | ✅       | ✅         |
| Priority Support| ❌       | ❌       | ✅         |
| SSO            | ❌        | ❌       | ✅         |
| Price/month    | Free      | $29      | $99        |

API Reference Table

| Endpoint | Method | Description | Auth |
|:---------|:------:|:------------|:----:|
| `/users` | `GET` | List all users | ✅ |
| `/users/:id` | `GET` | Get user by ID | ✅ |
| `/users` | `POST` | Create new user | ✅ |
| `/auth/login` | `POST` | Login | ❌ |
| `/health` | `GET` | Health check | ❌ |

Keyboard Shortcuts Table

| Action | Windows/Linux | macOS |
|:-------|:-------------|:------|
| Save | `Ctrl+S` | `⌘+S` |
| Undo | `Ctrl+Z` | `⌘+Z` |
| Find | `Ctrl+F` | `⌘+F` |
| New File | `Ctrl+N` | `⌘+N` |
| Bold | `Ctrl+B` | `⌘+B` |

Changelog Table

| Version | Date | Changes |
|:--------|:-----|:--------|
| 2.1.0 | 2026-07-01 | Added dark mode, fixed search bug |
| 2.0.0 | 2026-06-15 | Major UI redesign, new API |
| 1.5.2 | 2026-06-01 | Security patch, performance fix |
| 1.5.1 | 2026-05-20 | Bug fix for file upload |
| 1.5.0 | 2026-05-01 | Added file export feature |

Status Dashboard Table

| Service | Status | Uptime | Last Incident |
|:--------|:------:|-------:|:--------------|
| API | 🟢 Operational | 99.98% | 14 days ago |
| Web App | 🟢 Operational | 99.99% | 30+ days ago |
| Database | 🟡 Degraded | 99.90% | Today |
| CDN | 🟢 Operational | 100% | Never |
| Email | 🔴 Down | 98.50% | Now |

Tips for Better Tables

1. Align Pipes for Readability

The source doesn’t have to be perfectly aligned for rendering, but it helps readability:

<!-- Hard to read -->
|Name|Age|City|
|---|---|---|
|Alice|30|NYC|

<!-- Much better -->
| Name  | Age | City |
|-------|-----|------|
| Alice | 30  | NYC  |

2. Use Emoji for Visual Status

Replace boring text with visual indicators:

| Task           | Status |
|:---------------|:------:|
| Design review  | ✅     |
| Backend API    | 🔄     |
| Testing        | ⏳     |
| Deployment     | ❌     |

3. Keep Tables Narrow on Mobile

Wide tables with many columns don’t display well on phones. Consider:

• Splitting into multiple smaller tables
• Using only essential columns
• Abbreviating headers

4. Use HTML for Complex Needs

When Markdown tables aren’t enough, you can use HTML:

<table>
  <tr>
    <td rowspan="2">Merged Cell</td>
    <td>Cell 1</td>
  </tr>
  <tr>
    <td>Cell 2</td>
  </tr>
</table>

HTML tables support:

• rowspan and colspan for merged cells
• Nested lists inside cells
• Multiple paragraphs per cell
• Custom styling

5. Generate Tables from Data

For large tables, use online generators:

• Tables Generator — visual editor that exports Markdown
• CSV to Markdown — paste CSV data, get a table
• VS Code extensions — format tables automatically

Table Limitations in Markdown

Viewing Tables on Android

Most Markdown apps on Android render tables poorly — they overflow the screen, lose alignment, or don’t style them at all. MerMD handles tables properly:

• ✅ Proper column alignment — left, center, right
• ✅ Responsive layout — horizontal scroll for wide tables
• ✅ Styled headers — distinct header row styling
• ✅ Alternating rows — zebra striping for readability
• ✅ Dark mode — tables adapt to your theme
• ✅ Inline formatting — bold, code, links work inside cells

Frequently Asked Questions

Do I need the outer pipes in Markdown tables? No, but they’re recommended for readability. Both formats are valid.

Can I make a table without a header row? No — the header row is required in standard Markdown. If you don’t want headers, use empty header cells.

How many columns can a Markdown table have? There’s no technical limit, but readability drops after 5-6 columns. On mobile, 3-4 columns is optimal.

Can I sort Markdown tables? Not in the Markdown source. Tables are static. For sortable tables, you’d need JavaScript (not applicable in static Markdown viewing).