Markdown Tables: A Complete Syntax Guide for GitHub and Docs

Markdown was not originally designed with tables in mind. GitHub Flavored Markdown (GFM) added them later, and the syntax is strict in some places and surprisingly lenient in others. This guide shows every syntax rule you need, the platforms that support them, and the rendering quirks that cause tables to look broken in PRs and READMEs.

Minimum Valid Table

A valid Markdown table needs exactly three things: a header row, a separator row of dashes, and at least one body row. All three rows use pipe characters to separate cells.

| Name  | Stars |
| ----- | ----- |
| React | 230k  |
| Vue   | 210k  |

The leading and trailing pipes are optional in the GFM spec but every Markdown editor I have ever seen keeps them because they make the source readable. The separator row must have at least three dashes per cell. Any other character breaks the table and it falls back to regular text.

Column Alignment

Colons in the separator row control alignment.

| Left   | Center | Right  |
| :----- | :----: | -----: |
| apple  | banana | 100.00 |
| pear   | kiwi   |   5.50 |

• :--- left-aligned (also the default)
• :---: center-aligned
• ---: right-aligned

Right alignment is especially useful for numeric columns. Pair it with our Markdown Table Generator to avoid manually counting dashes.

Escaping the Pipe Character

A literal pipe inside a cell breaks the table because the parser treats it as a column separator. Escape it with a backslash.

| Operator | Meaning                |
| -------- | ---------------------- |
| \|\|      | Logical OR in many langs |
| \|       | Bitwise OR              |

If you have lots of pipes, wrap them in inline code with backticks. Backticks do not need to escape pipes because code is rendered verbatim.

| `||`    | Logical OR  |
| `|`     | Bitwise OR  |

Line Breaks Inside Cells

This is the most common source of broken Markdown tables. Cells cannot contain real newlines, the parser stops at the end of the line. For multi-line content, use the HTML <br> tag, which GFM allows inside tables.

| Feature | Details                        |
| ------- | ------------------------------ |
| Fast    | Sub-millisecond.<br>Cached.    |
| Safe    | SOC 2 Type II.<br>GDPR ready.  |

This renders correctly on GitHub, GitLab, Bitbucket and every static site generator that supports inline HTML. Platforms that strip HTML (some documentation sites, Notion export) will show the literal <br> text, which is why you often see tables avoiding multi-line content entirely.

Inline Formatting Inside Cells

Bold, italic, inline code, links and images all work inside cells. Block elements (headings, code blocks, blockquotes, nested lists) do not.

| Package | Status         | Docs                       |
| ------- | -------------- | -------------------------- |
| core    | **stable**     | [Read](https://docs.example.com/core)   |
| beta    | _experimental_ | [Read](https://docs.example.com/beta)   |
| next    | `preview`      | Coming soon                |

Images and Emoji in Cells

Standard Markdown image syntax works inside cells, which is perfect for status badges and icons in comparison tables.

| Service | Status                                         |
| ------- | ---------------------------------------------- |
| API     | ![](https://img.shields.io/badge/up-green)     |
| Web     | ![](https://img.shields.io/badge/up-green)     |
| Worker  | ![](https://img.shields.io/badge/down-red)     |

GitHub also renders :emoji-shortcodes: like :white_check_mark: and :x: in tables, which is the fastest way to mark checklist status without inline images.

Platform Support Cheat Sheet

CommonMark is the strict Markdown spec and does not include tables. If you see a table rendered as plain text, the parser is probably CommonMark-only. Every practical Markdown environment in 2026 uses GFM or a superset.

Common Rendering Pitfalls

• Missing blank line above the table. Some parsers need a blank line between the previous paragraph and the table header, otherwise they treat the header as a continuation.
• Cell count mismatch. Every row must have the same number of pipes as the header. Extra cells are silently dropped, missing cells render as empty.
• Tabs inside cells. Most renderers allow tabs, but they break alignment in the raw source. Stick to spaces in the Markdown file itself.
• Trailing whitespace in the separator row. Some stricter parsers reject | --- | --- | (trailing space after the last pipe). Clean it up.
• Missing closing newline. A table at the very end of the file needs a final newline. Most editors add it, but some diff tools strip it.

Converting from CSV or Excel

Rewriting a 20-row spreadsheet into Markdown by hand is brutal. Two options that work well:

• Paste the CSV or spreadsheet selection into our Markdown Table Generator, which autodetects comma, tab or semicolon delimiters.
• Use pandoc on the command line: pandoc -f csv -t gfm data.csv.

When to Skip Tables Entirely

Markdown tables work great for compact, tabular data. They struggle with long cells, nested lists and lots of formatting. If a single cell needs more than a couple of sentences, consider a definition list or a series of H3 headings instead. Your future self reviewing the diff will thank you.