Markdown Table Syntax Guide
The definitive technical guide to Markdown table syntax. Learn the GitHub Flavored Markdown (GFM) pipe table specification, alignment rules, escaping edge cases, multiline breaks, and platform support matrix.
Column Alignment (Left, Center, Right)
Use colons (:) in the delimiter row to left-align, center, or right-align columns.
Escaping Pipe Characters (\|)
How to include literal pipe characters inside table cells without breaking columns.
Line Breaks & Multiline Cells (<br>)
Add newlines and multi-line paragraphs inside table cells using HTML <br> tags.
1. Anatomy of a Standard Pipe Table
A standard GitHub Flavored Markdown table is composed of three mandatory structural components: a Header Row, a Delimiter Row, and one or more Data Rows.
| Feature | Free Plan | Pro Plan | | :------------ | :-------: | --------: | | Cloud Storage | 5 GB | 100 GB | | Team Members | 1 | Unlimited | | Price | $0.00 | $19.00 |
| Feature | Free Plan | Pro Plan |
|---|---|---|
| Cloud Storage | 5 GB | 100 GB |
| Team Members | 1 | Unlimited |
| Price | $0.00 | $19.00 |
Header Row
The first row defines column titles. Every table must have a header row; headerless tables are not supported in standard GFM.
Delimiter Row
The second row must contain at least 3 hyphen/colon characters per column (e.g. :---) to separate headers from body rows.
Data Rows
Each subsequent line forms a table row. Cell values are placed between vertical pipe characters.
Interactive Live Syntax Playground
Edit the markdown code below or click syntax snippet buttons to test how Markdown tables parse live.
| Product Name | Category | Status | Price |
|---|---|---|---|
| Mechanical Keyboard | Hardware | [x] In Stock | $129.99 |
| Ergonomic Mouse | Hardware | [x] In Stock | $79.50 |
| Cloud Backup Pro | Software | [ ] Waitlist | $9.99/mo |
2. Column Alignment Rules
Full Alignment GuideColumn alignment is controlled entirely inside the delimiter row using colons (:). Colons tell the parser whether to align content to the left, center, or right.
| Alignment | Syntax Pattern | Visual Rendering | Best Practice Use Case |
|---|---|---|---|
| Left Aligned | | :--- | or | :---: | | Text starts on left | Names, descriptions, narrative text (Default) |
| Centered | | :---: | | Balanced in center | Status badges, icons, dates, yes/no checks |
| Right Aligned | | ---: | | Aligns to the right | Prices, quantities, metrics, decimals |
3. Supported Cell Content & Inline Formatting
Markdown tables support almost all inline text formatting elements. However, block-level structures (like headings, blockquotes, or raw multi-line paragraphs) are prohibited.
Text Styling (Bold, Italic, Strikethrough)
Standard inline asterisks and tildes work seamlessly inside cells.
| **Bold Text** | *Italic Text* | ~~Deleted~~ |
Inline Code & Code Spans
Wrap functions, variables, or keys in backticks (`code`).
| `const result = true` | `npm install` |
Escaping Literal Pipes (\|)
Guide →Literal pipes must be escaped with a backslash (\|) to prevent splitting columns.
| Bitwise OR | `A \| B` or A \| B |
Multi-Line Cell Breaks (<br>)
Guide →Never press Enter inside a cell. Insert an HTML <br> tag for line breaks.
| Step 1<br>Step 2<br>Step 3 | Done |
4. Markdown Table Limitations & Practical Workarounds
Markdown tables prioritize human readability in plain text, which means certain complex features are not supported natively. Here is how to handle each limitation:
No Colspan / RowspanMerging cells across columns or rows
Standard GFM pipe tables cannot merge adjacent cells.
<table><td colspan="2">...</td></table>. GitHub, GitLab, and Obsidian render embedded HTML tables cleanly.No Native ListsBulleted or numbered markdown lists inside cells
Typing * Item 1 inside a cell will not render a native unordered list.
| Features | • First feature<br>• Second feature<br>• Third feature |No Headerless TablesCreating a table without column titles
In GFM, row 1 is always parsed as the header row.
| Property | Value |) or use our Transpose tool to structure data vertically.5. Markdown Flavors & Specifications Comparison
Different platforms use different Markdown parsers. Here is how major implementations handle table syntax:
| Markdown Flavor | Outer Pipes | Min Hyphens | Line Breaks | Headerless | Captions |
|---|---|---|---|---|---|
| GitHub Flavored Markdown (GFM) | Optional (Recommended) | 3 characters (---) | HTML <br> only | No (Header required) | No |
| GitLab Flavored Markdown (GLFM) | Optional (Recommended) | 3 characters (---) | HTML <br> only | No | No |
| CommonMark (Core v0.30) | Extension only (Not in core) | N/A (Requires GFM ext) | N/A | No | No |
| Obsidian Flavored Markdown | Optional | 3 characters (---) | HTML <br> only | No | No |
| Pandoc Markdown | Optional | 3 characters | Native multiline (Grid tables) | Yes (with extension) | Yes (: Table caption) |
| MultiMarkdown | Optional | 3 characters | HTML <br> | Yes | Yes ([Caption text]) |
6. Top 3 Markdown Table Syntax Mistakes
Mistake 1: Missing Blank Line Preceding the Table
Why it fails: If a table immediately follows regular text without an empty line, CommonMark parsers treat the pipe lines as continuation of the paragraph.
Mistake 2: Missing or Incomplete Delimiter Hyphens
Why it fails: Row 2 must contain hyphens (---). If omitted, the parser treats row 1 and row 2 as standard text.
Mistake 3: Unescaped Pipe in Cell Data
Why it fails: Writing foo | bar creates an accidental extra column, breaking table geometry.
7. Deep-Dive Syntax Guides
Column Alignment (Left, Center, Right)
Use colons (:) in the delimiter row to left-align, center, or right-align columns.
| :--- | :---: | ---: |
Escaping Pipe Characters (\|)
How to include literal pipe characters inside table cells without breaking columns.
| Value \| 1 | `foo | bar` |
Line Breaks & Multiline Cells (<br>)
Add newlines and multi-line paragraphs inside table cells using HTML <br> tags.
| Line 1<br>Line 2 |
Frequently Asked Questions About Markdown Table Syntax
Are outer pipes (|) required on the edges of Markdown tables?▼
In strict GitHub Flavored Markdown (GFM), outer boundary pipes at the beginning and end of each row are technically optional, meaning "Col 1 | Col 2" is valid. However, including outer pipes ("| Col 1 | Col 2 |") is strongly recommended because it prevents ambiguous parsing and renders reliably across all Markdown viewers.
Can I merge cells with colspan or rowspan in Markdown tables?▼
Standard Markdown (GFM, CommonMark, and MultiMarkdown) does NOT support colspan or rowspan. If your data requires merged cells, you can either duplicate cell content across columns, use an empty string as a placeholder, or embed raw HTML <table> markup.
Why is my Markdown table rendering as unformatted plain text on GitHub?▼
The most common cause is omitting an empty blank line immediately before the table. Most Markdown parsers will not switch into table mode if a table directly follows a paragraph or heading without a blank line in between.
How do I add line breaks inside a Markdown table cell?▼
Because raw linebreaks terminate the table row, you must use the HTML <br> or <br /> tag to insert line breaks inside a single cell.
How do I display a literal pipe character (|) inside a table cell?▼
You can either escape the pipe with a backslash (\|) or wrap the text in an inline backtick code span (`a | b`). Inside backticks, GFM parsers will not treat the pipe as a cell divider.
Can I include bulleted lists inside Markdown table cells?▼
Standard Markdown does not allow markdown bullet asterisks (*) inside table cells. To create a list inside a cell, use Unicode bullet points (•) separated by HTML <br> tags: "• Item 1<br>• Item 2".