Markdown Tables
Pipe-delimited table syntax, alignment, inline formatting, and the three most common mistakes that prevent tables from rendering.
Tables are a Markdown extension, not part of CommonMark. They work on GitHub, Notion, Obsidian, and most static-site generators, but not on Discord or Slack.
Basic Syntax
A Markdown table has three parts: a header row (column names), a separator line (at least one hyphen per column), and the data rows. All three are required.
| Name | Role | Location |
|---------|-------------|----------|
| Alice | Developer | NYC |
| Bob | Designer | LA |
| Charlie | PM | London || Name | Role | Location |
|---|---|---|
| Alice | Developer | NYC |
| Bob | Designer | LA |
| Charlie | PM | London |
Column Alignment
Add colons to the separator line to control alignment. The colon goes on the side you want the text flush against: :--- for left, :---: for center, ---: for right.
| Item | Price |
|:-------|----------:|
| Coffee | $3.50 |
| Bagel | $2.50 || Item | Price |
|---|---|
| Coffee | $3.50 |
| Bagel | $2.50 |
| Feature | Status | Score |
|:--------|:------:|------:|
| Dark mode | Yes | 95 |
| SSO | No | 0 || Feature | Status | Score |
|---|---|---|
| Dark mode | Yes | 95 |
| SSO | No | 0 |
Inline Formatting in Cells
Standard inline Markdown (bold, italic, code, links) works inside table cells. The only exception is block-level elements like blockquotes and multi-line code blocks, which are ignored inside tables by most renderers.
| Style | Syntax | Result |
|---------|---------------------|---------------|
| Bold | `**bold**` | **bold** |
| Italic | `*italic*` | *italic* |
| Code | ``code`` | `code` |
| Link | `[text](url)` | [Docs](https://example.com) || Style | Syntax | Result |
|---|---|---|
| Bold | **bold** |
bold |
| Italic | *italic* |
italic |
| Code | code |
code |
| Link | [text](url) |
Docs |
Escaping Pipes
If a cell needs to contain a literal pipe character (|), escape it with a backslash: \\|. Alternatively, wrap the content in backticks to treat it as inline code (pipes inside code are literal and do not need escaping).
| Command | Description |
|---------|--------------------------------|
| | grep | Filter output matching a pattern |
| | sort | Sort lines alphabetically || Command | Description |
|---|---|
| grep | |
| sort |
Line Breaks Inside Cells
Markdown tables do not support multi-line cells natively. The standard workaround is to insert an HTML <br> tag inside the cell. Most renderers that support tables also support this limited inline HTML.
| Column | Tall Column |
|--------|-------------|
| A | Line 1<br>Line 2<br>Line 3 |
| B | Single line || Column | Tall Column |
|---|---|
| A | Line 1 Line 2 Line 3 |
| B | Single line |
<br> in tables. GitHub, GitLab, and Docusaurus do. Discord and Slack do not support tables at all, so this is moot there.Common Mistakes
The three most common reasons a Markdown table fails to render. Each row shows the broken version and the corrected one side by side.
Broken
| Name | Role |
| Alice | Developer |
| Bob | Designer |Fixed
| Name | Role |
|-------|-----------|
| Alice | Developer |
| Bob | Designer |Broken
|Item|Price|
|---|---|
|Coffee| $5 |Fixed
| Item | Price |
|--------|-------|
| Coffee | $5 |Broken
| Name | Role |
|------|------|
|Alice | Dev
|Bob | Designer
|Charlie | PM |Fixed
| Name | Role |
|---------|-----------|
| Alice | Dev |
| Bob | Designer |
| Charlie | PM |Quick Reference
| Syntax | What it does |
|---|---|
| |---|---| | Required separator row between header and data |
| |---| | Minimum viable separator: one hyphen per column |
| :---| | Left-align the column (default is left even without the colon) |
| :---: | Center-align the column |
| ---: | Right-align the column |
| \| | Escape a literal pipe in a cell |
| `content` | Inline code in a cell (pipes are literal here) |
| <br> | Line break inside a cell (HTML workaround) |
Platform Support
Tables are not part of the CommonMark spec. Support is an extension that most major platforms have adopted, but not all.
| Platform | Supports | Notes |
|---|---|---|
| GitHub | Yes | Full support including alignment, inline formatting, and HTML in cells. |
| GitHub Wikis | Yes | Same support as GitHub repositories. |
| GitLab | Yes | Full support. Also supports multi-line cells via HTML. |
| Notion | Yes | Import Markdown tables or create native tables. Pasting pipe tables converts them. |
| Obsidian | Yes | Renders in both Live Preview and Reading view. No native table editing. |
| VS Code preview | Yes | Built-in Markdown preview renders table syntax correctly. |
| Reddit (new) | Yes | New Reddit supports Markdown tables. Old Reddit does not. |
| Discord | No | Tables are not supported. Use a code block or an image instead. |
| Slack | No | mrkdwn does not support tables. Use Block Kit or a code block. |
| Standard Markdown / CommonMark | No | Tables are an extension, not part of the CommonMark spec. |
| Pandoc | Yes | Full support including column width hints and complex cell layouts. |
| Docusaurus / VitePress / Astro | Yes | All static-site generators using remark/rehype support tables. |
Frequently Asked Questions
How do you create a table in Markdown?
Use pipe characters (|) to separate columns. Each row is on its own line. The first row is the header, the second row must be a separator line (|---|---|) with one or more hyphens per column, and subsequent rows contain the data. At minimum: a header row, a separator row, and at least one data row.
How do you align columns in a Markdown table?
Add colons to the separator line (|---|---|). :--- means left-aligned, :---: means center-aligned, and ---: means right-aligned. The colon goes on the side you want the text flush against. You can mix different alignments in the same table.
Can you put bold, italic, or links inside a table cell?
Yes. Markdown tables support inline formatting inside cells. You can write **bold**, *italic*, `code`, and [links](url) as you would in a normal paragraph. The formatting renders inside the cell.
Does Markdown support merging cells (rowspan or colspan)?
No. Markdown tables do not support merged cells natively. If you need colspan or rowspan, switch to raw HTML <table> tags. Most Markdown renderers that support tables will also pass inline HTML <table> through.
How do you escape a pipe inside a table cell?
Use a backslash before the pipe: \|. For example, \| grep renders as | grep in the cell. You can also wrap the cell content in backticks: `|` to preserve the literal character. Backtick-wrapped content is treated as inline code and does not need escaping.
Can you force a line break inside a table cell?
Standard Markdown tables do not support multi-line cells with line breaks. The workaround is to insert HTML <br> inside the cell. Most renderers that support Markdown tables also support a limited subset of inline HTML, including <br>. Example: Cell 1<br>Cell 2.
Why is my Markdown table not rendering?
The three most common causes are: (1) missing the separator line (the |---|---| row) between the header and data, (2) inconsistent row structure (some rows have more columns than others), or (3) a space before the first pipe (some parsers require the line to start with a pipe). Add the separator line, ensure every row has the same number of columns, and start each row with a pipe if a strict parser is refusing it.
Do Markdown tables work on Discord and Slack?
No. Discord does not support Markdown tables at all (pipe tables render as plain text). Slack's mrkdwn format also does not support tables. On both platforms, the best workaround is to format the data inside a code block so the column alignment is preserved, or upload an image.
How many columns can a Markdown table have?
There is no hard limit. Most renderers handle 10+ columns fine. The practical limit is visual readability. If a table has too many columns to fit comfortably on screen, consider splitting it into multiple tables or using a collapsible HTML <details> wrapper.
Related Markdown Guides
Tables are an extension to standard Markdown. For the rest of the syntax surface area: