The Complete Markdown Table Syntax Guide

Last updated: 2026-06-25

TL;DR

A markdown table separates cells with pipes (|) and puts a hyphen separator line (---) directly under the header.

Add a colon (:) to the separator to set column alignment, and escape a pipe inside a cell as \|.

1. The basic structure of a markdown table

A markdown table has at least three parts. The first line is the header, the second line is the separator, and the third line onward is the body data. Cells are separated by pipes (|), and the leading and trailing pipes on each line are optional.

| Name | Age | City |
| --- | --- | --- |
| John | 30 | Seoul |
| Jane | 25 | Busan |

The key is the separator on the second line. Directly under the header, each column needs at least three hyphens (---) for the markdown renderer to recognize the block as a table. Without the separator, it renders as plain text instead of a table.

2. Setting column alignment

Add a colon (:) to the separator line to set each column's alignment. The position of the colon decides the direction.

Separator notation and alignment
Notation	Alignment
`:---`	Left aligned
`:---:` or `:-:`	Center aligned
`---:`	Right aligned
`---`	Default (usually left, depends on renderer)

| Item | Qty | Amount |
| :--- | :-: | ---: |
| Apple | 3 | 4,500 |
| Pear | 1 | 3,000 |

In the example above, "Item" is left aligned, "Qty" centered and "Amount" right aligned. Right-aligning number columns lines up the digits and makes them easier to read.

3. Special characters inside cells (escaping)

If a cell's content contains a pipe (|), markdown mistakes it for a column separator and the table breaks. Escape it by putting a backslash before the pipe: \|. For example, to write "A or B" as "A | B" in a cell, enter A \| B. The Text Tools markdown table generator escapes pipes inside cells automatically.

4. Line breaks and inline formatting in cells

You cannot press Enter to break a line inside a markdown table cell. To show a cell on two lines, put a <br> tag in the cell. You can also use inline formatting inside cells, such as bold (**bold**), italics (*italic*), inline code (`code`) and links ([text](URL)).

5. Checklist for when a table breaks

Check the separator — make sure there is a | --- | --- | separator line right under the header. This is the most common mistake.
Match column counts — where possible, match the number of pipes in every row to the header. Fill missing cells with an empty cell (| |).
Escape pipes — confirm that any | in cell content is written as \|.
Surround with blank lines — leaving a blank line above and below the table makes recognition more reliable in some renderers.
Pipes, not tabs — tab-separated data copied from a spreadsheet is not recognized as a table, so convert it to the pipe format. You can do that automatically with the markdown table generator.

6. Where you can paste it

Markdown tables work in GitHub README files, Notion, Obsidian, GitLab, Discord and most static blogs that support markdown. Note that cell merging (rowspan/colspan) is not supported in standard markdown, so for complex tables consider writing HTML table tags directly or splitting the table into several.

Frequently Asked Questions (FAQ)

How do I add a line break inside a markdown table cell?

You cannot press Enter to break a line inside a markdown table cell. Instead, put a <br> tag in the cell content and most renderers, including GitHub and Notion, will show it as a line break.

What is the most common reason a table looks broken?

The two most common causes are omitting the separator line (the --- row) right under the header, and not escaping a pipe (|) inside a cell. Without the separator the block is not recognized as a table, and an unescaped pipe splits columns incorrectly.

How do I set cell alignment?

Add colons to the separator line. :--- is left, :-: is center and ---: is right aligned. Without a colon, the renderer default (usually left) applies.

Related tools

Markdown Table Generator — enter data and it builds the table with alignment and escaping automatically.
Remove Duplicate Lines — sort and clean up the items going into a table.
Word Counter — check the character count of table cells.

Last updated: 2026-06-25