Markdown Tables Guide

Everything you need to know about markdown tables. Each section includes syntax, examples, and a link to try it live in the Table Formatter.

1. Basic Table Syntax

A markdown table needs three things: a header row, a separator row with dashes, and one or more data rows. Columns are separated by pipes (|).

| Name       | Role       | Location   |
|------------|------------|------------|
| Alice      | Engineer   | Berlin     |
| Bob        | Designer   | London     |
| Carol      | PM         | New York   |

Try in Table Formatter

The separator row (the one with dashes) tells the markdown processor that the first row is a header. You need at least three dashes per column.

2. Column Alignment

Control column alignment by adding colons to the separator row. A colon on the left means left-aligned, on the right means right-aligned, and colons on both sides means centered.

:--- left-aligned (default)

:---: centered

---: right-aligned

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Alice        |    Engineer    |        90,000 |
| Bob          |    Designer    |        85,000 |
| Carol        |       PM       |        95,000 |

Try in Table Formatter

Right-alignment is especially useful for numeric columns like prices, counts, or percentages so the digits line up visually.

3. Formatting in Cells

You can use most inline markdown inside table cells: bold, italic, strikethrough, inline code, and links.

| Feature      | Status          | Notes                        |
|--------------|-----------------|------------------------------|
| **Auth**     | `done`          | Uses [OAuth 2.0](https://oauth.net) |
| *Search*     | `in-progress`   | Full-text with **Postgres**  |
| ~~Legacy~~   | `deprecated`    | Remove in v3                 |

Try in Table Formatter

Block-level elements like headings, lists, and blockquotes are not supported inside table cells. Stick to inline formatting.

4. Multi-line Content

Markdown tables don't natively support line breaks within cells. Use the HTML <br> tag to insert line breaks when you need multi-line cell content.

| Method | Endpoint         | Description                                 |
|--------|------------------|---------------------------------------------|
| GET    | /api/users       | List all users.<br>Supports pagination.     |
| POST   | /api/users       | Create a new user.<br>Requires admin token. |
| DELETE | /api/users/:id   | Delete a user.<br>Returns 204 on success.   |

Try in Table Formatter

This works on GitHub, GitLab, and most markdown renderers that allow inline HTML. Keep cell content concise — if you need paragraphs, consider using a different format.

5. Wide Tables

Tables with many columns can be hard to read in raw markdown. Here are some strategies for handling wide tables.

| ID | Name  | Email             | Role     | Team      | Location | Start Date | Status |
|----|-------|-------------------|----------|-----------|----------|------------|--------|
| 1  | Alice | alice@example.com | Engineer | Platform  | Berlin   | 2022-01-15 | Active |
| 2  | Bob   | bob@example.com   | Designer | Product   | London   | 2021-06-01 | Active |
| 3  | Carol | carol@example.com | PM       | Product   | New York | 2023-03-20 | Active |

Try in Table Formatter

Tips for wide tables:

Don't pad columns to equal widths — most renderers ignore whitespace anyway
Use the Table Formatter to auto-align columns for readability
Consider splitting into multiple tables if you have more than 7-8 columns
Abbreviated headers help keep things compact

6. Common Patterns

Ready-to-copy templates for the most common table types.

Comparison Table

Great for pricing pages, plan comparisons, or tool evaluations.

| Feature        | Free   | Pro     | Enterprise |
|----------------|--------|---------|------------|
| Users          | 5      | 50      | Unlimited  |
| Storage        | 1 GB   | 100 GB  | 1 TB       |
| API access     | No     | Yes     | Yes        |
| SSO            | No     | No      | Yes        |
| Support        | Email  | Chat    | Dedicated  |
| Price (month)  | $0     | $29     | Custom     |

Try in Table Formatter

Feature Matrix

Center-aligned columns work well for Yes/No feature grids.

| Feature        | macOS | Windows | Linux |
|----------------|:-----:|:-------:|:-----:|
| Auto-update    |  Yes  |   Yes   |  No   |
| Dark mode      |  Yes  |   Yes   |  Yes  |
| Touch Bar      |  Yes  |   N/A   |  N/A  |
| System tray    |  Yes  |   Yes   |  Yes  |
| ARM support    |  Yes  |   Yes   |  Yes  |

Try in Table Formatter

API Reference Table

A standard layout for documenting API parameters or configuration options.

| Parameter   | Type     | Required | Default | Description                      |
|-------------|----------|:--------:|---------|----------------------------------|
| `page`      | integer  |    No    | `1`     | Page number for pagination       |
| `per_page`  | integer  |    No    | `20`    | Items per page (max 100)         |
| `sort`      | string   |    No    | `desc`  | Sort order: `asc` or `desc`       |
| `q`         | string   |   Yes    | —       | Search query string              |

Try in Table Formatter

Pricing Table

Right-align price columns for clean number formatting.

| Plan         | Monthly | Annual (per mo.) | Storage | Support   |
|:-------------|--------:|-----------------:|--------:|:----------|
| Starter      |      $9 |               $7 |    5 GB | Community |
| Professional |     $29 |              $24 |   50 GB | Email     |
| Business     |     $79 |              $66 |  500 GB | Priority  |
| Enterprise   | Custom  |           Custom | Custom  | Dedicated |

Try in Table Formatter

7. Tips & Best Practices

Keep tables readable in raw markdown

Align pipes vertically so the table reads well in plain text editors — the Table Formatter does this automatically
Leading and trailing pipes are optional but recommended for consistency
Use consistent column widths within a table

When to use tables

Structured data with clear column headers
Feature comparisons across products or plans
API parameter or configuration references
Quick-reference data (keyboard shortcuts, status codes)

When to avoid tables

Long-form text — paragraphs don't belong in cells
Deeply nested or hierarchical data — use headings or lists instead
Single-column data — a list is simpler and easier to read
Data that changes frequently — consider generating tables from a data source

Escaping pipes

If your cell content contains a literal pipe character, escape it with a backslash: \|. Inside inline code spans (backticks), pipes don't need escaping.

8. Table Formatter Tool

Tired of manually aligning table columns? The Table Formatter takes your messy table and produces perfectly aligned, GFM-compatible output in one click.

Open Table Formatter