Markdown Table Syntax — How to Build Tables with Pipe Characters

Quick answer: Markdown tables use pipe characters | and hyphens -. Nothing else required.

| Name | Email | Role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

If typing pipes by hand is not your idea of a good time, paste CSV into CSV to Markdown and get a formatted table instantly. The rest of this article walks through the syntax in detail.

Basic syntax — pipes and hyphens

A Markdown table has three parts:

1. Header row — column names separated by pipes |
2. Separator row — at least three hyphens - per column, separating the header from data
3. Data rows — cell values separated by pipes

| Item | Value |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

Leading and trailing pipes are optional but recommended for readability. Column widths do not need to be aligned in the source; the renderer handles that.

Column alignment — left, center, right

Add colons : to the separator row to control alignment:

| Product | Qty | Price |
| :--- | :---: | ---: |
| Apples | 3 | 1.20 |
| Oranges | 10 | 0.80 |

Right-aligning numeric columns keeps digits lined up and makes the table easier to scan.

GFM (GitHub Flavored Markdown) support

GitHub, GitLab, Zenn, Qiita, Notion, Obsidian, and most developer-facing platforms support GFM table syntax. Everything shown above works as-is on these platforms.

A few things worth remembering about GFM tables:

• The header row is mandatory. You cannot create a headerless table in GFM
• The separator row needs at least three hyphens (---) per column
• Inline formatting (`code`, links, strikethrough) works inside cells
• Some parsers require a blank line before and after the table to recognize it

Common pitfalls

Pipe characters inside cells

A literal | in a cell breaks the column structure. Escape it with a backslash:

| Command | Meaning |
| --- | --- |
| cmd1 \| cmd2 | pipe two commands |

Newlines inside cells

The Markdown table spec does not support line breaks within a cell. If you need a visible break, write an HTML <br> tag directly, though not all platforms render it.

Empty cells

Leave a space (or nothing) between two pipes. A space is preferred for readability:

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

Mismatched column counts

If a data row has fewer columns than the header, most parsers pad with empty cells. If it has more, the extras are silently dropped. Keeping column counts consistent avoids surprises.

Large datasets — generate from CSV

Hand-writing a five-row table is fine. Past 20 rows, or with many columns, it becomes tedious and error-prone. Copy data from Excel or a spreadsheet as CSV, paste it into CSV to Markdown, and the tool handles pipe alignment and escaping for you.

For a step-by-step walkthrough, see How to Convert CSV to a Markdown Table. If you need to turn the resulting Markdown table into HTML, see Markdown to HTML conversion guide.

FAQ

Can I create a Markdown table without a header?

Not in GFM. The header row and separator row are both required. If you do not need visible headers, you still have to include them — use placeholder text or empty header cells.

Can I put links or images inside a cell?

Yes. Inline Markdown like [text](url) and ![alt](image-url) works inside cells. Keep in mind that wide cells make the source hard to read, so links are usually the practical limit.

Can I control column widths?

Markdown has no column-width syntax. Renderers size columns based on content. For precise control, fall back to an HTML <table>.

Wrapping up

Markdown table syntax is straightforward: pipes for columns, hyphens for the separator, colons for alignment. Once you know these three pieces, you can build any table.

When the data gets large, skip the manual work. Paste CSV into CSV to Markdown and get a clean, correctly escaped table in seconds.