Markdown Tables
Comprehensive guide to creating and formatting tables in markdown.
Basic Table Syntax
| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Renders as:
Header 1 Header 2 Header 3
Cell 1 Cell 2 Cell 3
Cell 4 Cell 5 Cell 6
Column Alignment
| Left | Center | Right |
|---|---|---|
| Left | Center | Right |
| aligned | aligned | aligned |
Renders as:
Left Center Right
Left Center aligned
text text text
-
:--- Left align (default)
-
:--: Center align
-
---: Right align
Minimum Syntax
The pipes and dashes don't need to align:
| Header | Header |
|---|---|
| Cell | Cell |
However, aligned tables are more readable in source.
Escaping Pipe Characters
Use | to include a literal pipe in a cell:
| Command | Description |
|---|---|
a | b | Pipe operator |
cmd || exit | Or operator |
Inline Formatting in Tables
Tables support inline markdown:
| Feature | Syntax |
|---|---|
| Bold | **text** |
| Italic | *text* |
Code | `code` |
| Link | [text](url) |
Multi-line Cell Content
Standard markdown tables don't support multi-line cells. Workarounds:
Using <br> Tags
| Step | Description |
|---|---|
| 1 | First line<br>Second line |
| 2 | Another step |
Using HTML Tables
For complex layouts, use HTML:
<table> <tr> <th>Header</th> <th>Description</th> </tr> <tr> <td>Item</td> <td> <ul> <li>Point one</li> <li>Point two</li> </ul> </td> </tr> </table>
Empty Cells
Use a space or leave empty:
| A | B | C |
|---|---|---|
| 1 | 3 | |
| 4 | 5 |
Wide Tables
For tables with many columns, consider:
Scrollable Container (HTML)
<div style="overflow-x: auto;">
| Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 |
|---|---|---|---|---|---|
| Data | Data | Data | Data | Data | Data |
</div>
Vertical Layout
Transform wide tables into key-value pairs:
Item 1
| Property | Value |
|---|---|
| Name | Foo |
| Type | Bar |
| Status | Active |
Common Table Patterns
Comparison Table
| Feature | Free | Pro | Enterprise |
|---|---|---|---|
| Users | 5 | 50 | Unlimited |
| Storage | 1GB | 10GB | 100GB |
| Support | ❌ | ✅ | ✅ |
API Reference
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | ✅ | Unique identifier |
name | string | ✅ | Display name |
limit | number | ❌ | Max results (default: 10) |
Keyboard Shortcuts
| Action | Windows/Linux | macOS |
|---|---|---|
| Copy | Ctrl+C | ⌘+C |
| Paste | Ctrl+V | ⌘+V |
| Undo | Ctrl+Z | ⌘+Z |
Changelog
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2024-01-15 | Breaking: New API |
| 1.2.0 | 2024-01-01 | Added feature X |
| 1.1.0 | 2023-12-15 | Bug fixes |
Best Practices
-
Keep tables simple: If content is complex, consider alternatives
-
Use consistent alignment: Align source pipes for readability
-
Header row required: Always include a header row
-
Escape special characters: Use | for literal pipes
-
Limit columns: Wide tables are hard to read
-
Consider alternatives: Lists or definition lists may work better
-
Test rendering: Tables render differently across platforms
Markdownlint Rules for Tables
Rule Description
MD055 Table pipe style should be consistent
MD056 Table column count should match header
MD058 Tables should be surrounded by blank lines
Alternatives to Tables
Definition Lists (Some Parsers)
Term 1 : Definition 1
Term 2 : Definition 2
Bullet Lists with Bold Keys
- Name: John Doe
- Email: john@example.com
- Role: Developer
Nested Lists
- Item 1
- Property A: Value
- Property B: Value
- Item 2
- Property A: Value
- Property B: Value