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:

Column Alignment

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| Left     | Center   | Right    |
| aligned  | aligned  | aligned  |

Renders as:

• :--- 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](url) | `[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

1. Keep tables simple: If content is complex, consider alternatives
2. Use consistent alignment: Align source pipes for readability
3. Header row required: Always include a header row
4. Escape special characters: Use \| for literal pipes
5. Limit columns: Wide tables are hard to read
6. Consider alternatives: Lists or definition lists may work better
7. Test rendering: Tables render differently across platforms

Markdownlint Rules for Tables

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