---

name: markdown-tables description: Use when creating or formatting tables in markdown. Covers table syntax, alignment, escaping, and best practices. allowed-tools:

• Read
• Write
• Edit
• Grep
• Glob

---

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](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

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