Markdown Table Examples

The standard Markdown table uses pipes (|) and hyphens (-) to separate columns and rows.

| Name | Role | Team |
|------|------|------|
| Alex | Developer | Platform |
| Sarah | Designer | Product |
| Emma | QA Engineer | Testing |

Result

Best for

• Team lists
• Documentation
• Simple data

You can align text left, center, or right.

| Feature | Status | Score |
|:---------|:------:|------:|
| Login | Complete | 100 |
| Payments | In Progress | 70 |
| Reports | Planned | 20 |

Result

Why this structure works

Alignment makes numerical columns easier to scan while keeping text readable.

A common format for product documentation and README files.

| Feature | Free | Pro |
|---------|:----:|:---:|
| Unlimited Projects | ❌ | ✅ |
| Team Collaboration | ❌ | ✅ |
| Export PDF | ✅ | ✅ |
| Priority Support | ❌ | ✅ |

Result

Best for

• Pricing pages
• SaaS documentation
• Product comparisons

Useful when documenting endpoints and responses.

| Status Code | Meaning |
|------------|---------|
| 200 | Success |
| 201 | Resource created |
| 400 | Invalid request |
| 401 | Authentication required |
| 404 | Resource not found |
| 500 | Server error |

Result

Perfect for installation guides and project documentation.

| Option | Default | Description |
|--------|---------|-------------|
| theme | light | Interface theme |
| autosave | true | Save changes automatically |
| language | en | Display language |
| timeout | 30 | Request timeout in seconds |

Result

Best for

• Configuration reference
• CLI documentation
• Software settings

Track progress directly inside Markdown.

| Task | Owner | Status | Due |
|------|-------|--------|-----|
| Homepage | Emma | ✅ Done | 12 Jul |
| API Docs | Liam | 🚧 In Progress | 15 Jul |
| Release Notes | Noah | ⏳ Planned | 20 Jul |

Result

Useful when comparing platforms.

| Platform | Tables | Task Lists | Mermaid |
|----------|:------:|:----------:|:--------:|
| GitHub | ✅ | ✅ | ✅ |
| GitLab | ✅ | ✅ | ✅ |
| Obsidian | ✅ | ✅ | ✅ |
| Standard Markdown | ⚠️ Depends | ❌ | ❌ |

Result

Why this structure works

Comparison tables help readers quickly identify differences between platforms without reading long paragraphs.

Ideal for technical documentation.

| Property | Value |
|----------|-------|
| Version | 2.4.0 |
| License | MIT |
| Language | TypeScript |
| Platform | Cross-platform |

Result

| Name | Department | Email |
|------|------------|-------|
| Olivia | Marketing | olivia@example.com |
| Ethan | Engineering | ethan@example.com |
| Mia | Support | mia@example.com |

Result

| Version | Date | Highlights |
|---------|------|------------|
| 2.1.0 | Jun 2026 | Added API support |
| 2.0.0 | Apr 2026 | New UI |
| 1.9.5 | Feb 2026 | Bug fixes |

Result

| Resource | Link |
|----------|------|
| Documentation | https://example.com/docs |
| API | https://example.com/api |
| GitHub | https://github.com/example/project |

Result

| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run build` | Build the project |
| `npm test` | Run tests |

Result

Best for

• CLI documentation
• Command references
• Installation guides

Keep Tables Focused#

A table works best when readers can compare information quickly. If a column doesn't help answer the reader's question, consider removing it.

Good

| Feature | Supported |
|---------|-----------|
| Tables | Yes |
| Task Lists | Yes |
| Footnotes | No |

Less effective

| Feature | Supported | Added By | Developer | Internal Notes | Reference |
|---------|-----------|----------|-----------|----------------|----------|

A simpler table is easier to scan and works better on both desktop and mobile devices.

Use Clear Column Headings#

Column names should explain the data without forcing readers to guess.

Good headings: Feature, Description, Status, Version, Command, Output

Avoid vague headings like: Info, Data, Item, Value 1, Misc

Specific headings make documentation easier to understand.

Keep Similar Data Together#

Each column should contain one type of information.

Good

| Package | Version | License |
|---------|---------|---------|
| Express | 5.0 | MIT |
| React | 19 | MIT |

Avoid mixing unrelated values in the same column

| Package |
|---------|
| Express - MIT - Version 5 |

Splitting information into separate columns improves readability.

Align Numbers for Easier Comparison#

When a column contains prices, scores, percentages, or version counts, right-aligning the values makes them easier to compare.

| Project | Stars |
|---------|------:|
| Alpha | 125 |
| Beta | 2,340 |
| Gamma | 18,945 |

This is especially useful for reports and analytics.

Keep Formatting Consistent#

Choose one style and use it throughout the document. For example, if one table uses title case headings, status icons, and left-aligned text, follow the same pattern in every table. Consistent formatting makes documentation feel professional and easier to navigate.

Use Tables Only When They Improve Clarity#

Not every list belongs in a table. A simple list is often easier to read than a table with only one column.

Instead of this:

| Supported Formats |
|-------------------|
| PDF |
| HTML |
| DOCX |

Use a list:

- PDF
- HTML
- DOCX

Choose the format that makes the information easiest to understand.

Keep Cell Content Short#

Tables are designed for scanning, not reading long paragraphs. Instead of writing several sentences inside a cell, summarize the information and link to a dedicated section if more explanation is needed.

Test Your Tables#

Different Markdown editors and platforms can render tables slightly differently. Before publishing, preview your document to make sure:

• Columns line up correctly
• Long text wraps as expected
• Links work
• Inline code displays properly
• Mobile layouts remain readable

A quick preview helps catch formatting issues before readers see them.

Forgetting the Header Separator#

Every Markdown table needs a separator row beneath the headings.

Incorrect

| Name | Role |
| Alex | Developer |

Correct

| Name | Role |
|------|------|
| Alex | Developer |

Using Different Numbers of Columns#

Every row should contain the same number of columns.

Incorrect

| Name | Role | Team |
|------|------|------|
| Alex | Developer |

Correct

| Name | Role | Team |
|------|------|------|
| Alex | Developer | Platform |

Turning Everything into a Table#

Tables aren't always the best choice. Use lists for collections, headings for sections, and tables for comparisons and structured data. Choosing the right format improves readability.

Writing Long Paragraphs Inside Cells#

Large blocks of text make tables difficult to read. Instead, keep each cell concise and explain complex topics below the table if needed.

Using Too Many Columns#

Wide tables become difficult to read, especially on smaller screens. If a table contains eight or more columns, consider splitting it into multiple tables, removing unnecessary columns, or moving detailed information into separate sections. Readers can process smaller tables much more quickly.