Tables are one of the most useful — and most misused — features in markdown. When they're appropriate, a well-formatted table communicates structure more clearly than any paragraph could. When they're not appropriate, they're a maintenance nightmare.

This guide covers the full table syntax, every alignment option, what you can embed in cells, and the edge cases that trip people up.

Basic Table Syntax

A markdown table is built from three parts: the header row, the separator row, and the data rows.

| Column One | Column Two | Column Three |
|------------|------------|--------------|
| Cell A     | Cell B     | Cell C       |
| Cell D     | Cell E     | Cell F       |

Which renders as:

Column One	Column Two	Column Three
Cell A	Cell B	Cell C
Cell D	Cell E	Cell F

The rules:

Columns are separated by pipe characters (|)
The separator row must have at least three dashes per cell (---)
The opening and closing pipes are optional but conventional
Cells don't need to be padded to equal width (though it helps readability in the source)

A minimal valid table:

Header 1 | Header 2
--- | ---
Cell A | Cell B

Column Alignment

Add colons to the separator row to control alignment:

| Left-aligned | Centered | Right-aligned |
|:-------------|:--------:|--------------:|
| Text         | Text     | Text          |
| More text    | More     | More          |

Left-aligned	Centered	Right-aligned
Text	Text	Text
More text	More	More

:--- — left align (this is the default)
:---: — center align
---: — right align

Right-alignment is useful for numbers and prices. Center-alignment works for short labels or checkmarks. Most tables default to left for everything else.

Embedding Formatting in Cells

You can use most inline markdown inside table cells:

Bold and italic:

| Name | Status |
|------|--------|
| **Critical** | *Needs review* |
| Normal | Ready |

Inline code:

| Method | Description |
|--------|-------------|
| `GET /users` | Fetch all users |
| `POST /users` | Create a user |

Method	Description
`GET /users`	Fetch all users
`POST /users`	Create a user

Links:

| Tool | Link |
|------|------|
| OpenMark | [Download](https://openmarkapp.com) |
| Homebrew | [Install](https://brew.sh) |

Checkmarks (useful for comparison tables):

| Feature | Pro | Free |
|---------|-----|------|
| Export  | ✓   | —    |
| Sync    | ✓   | —    |

What you can't embed: Block-level elements. You can't put a code block, list, or another table inside a table cell. If you need that, restructure your content.

The Pipe Escape Problem

If you need a literal | character inside a cell, escape it with a backslash:

| Pattern | Meaning |
|---------|---------|
| `a\|b` | Matches a or b |

Similarly, in code cells you may need to use HTML entities: | for |.

GFM Tables vs Other Markdown Flavors

Markdown tables are a GitHub Flavored Markdown (GFM) extension — they're not part of the original Markdown specification. This matters because:

GitHub, GitLab, Bitbucket: Full GFM support, tables render natively
CommonMark: No table support in the base spec
Pandoc Markdown: Tables supported, but different syntax (grid tables, pipe tables)
R Markdown / Quarto: Support pipe tables (GFM syntax)
MultiMarkdown: Tables supported, slightly different alignment syntax

For most developer workflows — README files, documentation sites built on Docusaurus/VitePress/Nextra, GitHub issues and PRs — GFM tables work everywhere.

On macOS: OpenMark renders GFM tables natively with zebra striping (alternating row background colors) for easier reading on wide tables. VS Code requires an extension or the built-in preview pane; MacDown doesn't support GFM tables at all. For a comparison of how different editors handle GFM features, see The Best Markdown Editors for Mac in 2026.

Making Tables Readable in Source

Tables are the markdown syntax that's hardest to edit in plain text. A wide table with many columns is a mess of pipes and spaces. A few habits help:

Align your columns. It takes more time to write, but a source table that lines up is much easier to maintain:

| Name       | Version | License  | Stars |
|------------|---------|----------|-------|
| OpenMark   | 1.2.0   | MIT      | 1.2k  |
| Typora     | 1.8.0   | Paid     | 8.7k  |

versus the minimal-but-messy alternative:

|Name|Version|License|Stars|
|---|---|---|---|
|OpenMark|1.2.0|MIT|1.2k|

Both render identically. The first is readable in source. The second isn't.

Use a table generator for complex tables. Rather than counting pipes manually, use a markdown table generator tool (there are many online) to create the initial structure, then paste it into your editor.

OpenMark tip: When working on a document with complex tables, the rendered view in OpenMark shows you the formatted table immediately. You toggle to edit mode, fix the source, and toggle back to verify — faster than waiting for a preview pane to refresh.

When to Use Markdown Tables

Tables are the right tool when:

You have clearly defined columns and rows. Comparison tables, API parameter lists, changelog entries, environment variable references.
The content is truly tabular. Each cell holds a value for an attribute of a row item.
The data is relatively stable. Tables are more painful to update than prose.

When NOT to use markdown tables:

Tables are the wrong tool when:

You're comparing two things with many details. A detailed comparison with paragraphs of explanation per row doesn't fit in a table cell. Use sections instead.
Your "table" is really a list. If one column is just a label and the other is a sentence, that's a definition list, not a table.
The data has many blank cells. A sparse table is usually a sign the data doesn't have a true tabular structure.
You need nested structure. If cells contain lists or paragraphs, restructure your document rather than trying to force it into a table.

Column Width Considerations

Markdown tables expand to fit content. On narrow screens (phones, small browser windows), wide tables overflow horizontally. A few approaches:

Keep cell content short. Abbreviate where possible. Use footnotes for long explanations.

Consider using a list for mobile-first docs. In documentation that'll be read on phones, a definition list or a section-per-item structure often works better than a table.

HTML for complex cases. If you genuinely need a complex table (merged cells, fixed widths), use raw HTML inside your markdown. Most markdown processors pass HTML through unchanged.

Real-World Table Examples

API endpoint reference:

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/users` | GET | Bearer | List users |
| `/users/:id` | GET | Bearer | Get user |
| `/users` | POST | Bearer | Create user |
| `/users/:id` | DELETE | Bearer | Delete user |

Feature comparison:

| Feature | Free | Pro | Enterprise |
|---------|------|-----|------------|
| Users | 1 | 10 | Unlimited |
| Storage | 5GB | 100GB | Unlimited |
| API access | — | ✓ | ✓ |
| SLA | — | — | 99.9% |

Changelog:

| Version | Date | Changes |
|---------|------|---------|
| 2.1.0 | 2026-02-15 | Added Mermaid rendering |
| 2.0.0 | 2026-01-10 | macOS Tahoe support |
| 1.9.5 | 2025-11-20 | Bug fixes |

For the complete markdown syntax reference including headings, lists, code blocks, and LaTeX math, see the Markdown Cheat Sheet for Mac Users.

Try OpenMark

OpenMark renders GFM tables with proper formatting — zebra striping, aligned columns, inline code in cells — all without any configuration.

Download OpenMark on the Mac App Store → $9.99 one-time. Native macOS. openmarkapp.com