GameParticles
Text

Markdown Table Syntax: Alignment, Escaping and Line Breaks

Write a Markdown table with pipes and hyphens, align columns with colons, escape pipes inside cells, add line breaks, and learn what tables cannot do.

Updated

A Markdown table is built from pipes and hyphens: a header row, a delimiter row of hyphens, then one line per data row, with | between cells. Colons in the delimiter row set column alignment. Tables are an extension from GitHub Flavored Markdown, not part of original Markdown, so they work on GitHub and most modern editors but not in every parser.

Basic syntax

Here is the source of a three-column table. Each line of the source is one row of the table.

  • | Name | Role | City |
  • | ----- | -------- | ------ |
  • | Ada | Engineer | London |
  • | Grace | Admiral | NYC |

It renders like this:

NameRoleCity
AdaEngineerLondon
GraceAdmiralNYC

The rules, as defined in the GitHub Flavored Markdown (GFM) specification:

  1. The first line is the header row. A table cannot be written without one.
  2. The second line is the delimiter row. Each cell contains only hyphens, with optional colons for alignment. Three hyphens per column is the convention and the safest choice across parsers.
  3. The header row and the delimiter row must have the same number of cells, or the block is not treated as a table.
  4. Every following line is a data row, until a blank line or another block element ends the table.
  5. Spaces around cell content are ignored, so the pipes do not have to line up. Padding the columns just makes the source easier to read.

Put a blank line before the table. Some parsers will not recognize a table that directly follows a paragraph.

Leading and trailing pipes

GFM treats the pipes at the start and end of each row as optional, so this is also a table on GitHub:

  • Name | Role
  • --- | ---
  • Ada | Engineer

Keep the outer pipes anyway. They are recommended by the specification, they make single-column tables possible, and simpler parsers require them.

Column alignment

Alignment is set per column with colons in the delimiter row.

Delimiter cellAlignment
---Default, usually left
:---Left
:---:Center
---:Right

A table with a left-aligned label, a centered status and a right-aligned amount looks like this in the source:

  • | Item | Status | Price |
  • | :----- | :----: | ----: |
  • | Coffee | In | 3.50 |
  • | Tea | Out | 12.00 |

Right-align columns of numbers so the digits line up. Alignment applies to the whole column, header included; there is no way to align a single cell.

Formatting inside cells

Cells accept inline Markdown: bold, italic, inline code, links and images all work. Block elements do not. You cannot put a heading, a list, a blockquote or a fenced code block inside a cell.

Escaping pipes

Because the pipe separates cells, a literal pipe in your content has to be escaped with a backslash: write \|. This matters most in tables that document shell commands, regular expressions or TypeScript union types.

In GFM the escape is needed even inside inline code. A code span containing a \| b in a table cell is displayed as a, pipe, b with the backslash removed. Outside tables that same backslash would be shown literally, which is a common source of confusion when moving text into and out of a table.

Where the renderer allows HTML, the entity | is an alternative that also produces a pipe character in normal text.

Line breaks in cells

A table row must be one line of source, so pressing Enter inside a cell ends the row. For a visible line break within a cell, use the HTML tag <br>:

  • | Step | Details |
  • | --- | --- |
  • | 1 | Install the package<br>Restart the server |

This works on GitHub and in most renderers that pass HTML through. It does not work where HTML is stripped or escaped, including some chat apps and comment systems. In those places, split the content into two rows or move the detail below the table.

What Markdown tables cannot do

The syntax is deliberately small. It has no way to express:

  • Merged cells, meaning column spans or row spans
  • Tables without a header row
  • Multi-line source for a single cell
  • Lists, code blocks or multiple paragraphs inside a cell
  • Column widths, borders, colors or captions
  • Row headers, where the first cell of each row is a header

For any of these, write an HTML table element instead. GitHub and many other renderers accept raw HTML in Markdown files. Some writers imitate a headerless table by leaving every header cell empty; it renders, but an empty header row is announced as such by screen readers.

Rows are forgiving in one respect. In GFM, a data row with fewer cells than the header is padded with empty cells, and extra cells beyond the header count are ignored.

Where tables work

Tables were introduced by PHP Markdown Extra and adopted by GFM. They are not in the CommonMark core specification, so support depends on the tool. GitHub, GitLab, most static site generators, documentation tools and note apps render them. Plain CommonMark parsers with no extensions enabled show the pipes and hyphens as ordinary text.

The rest of the syntax, from headings to task lists, is in the Markdown cheat sheet.

Practical tips

  • Keep tables narrow. Wide tables force horizontal scrolling on phones; four or five columns is a comfortable limit for prose.
  • Keep cells short. If a cell needs a paragraph, the content probably belongs in a list or under its own heading.
  • Do not align the source by hand in large tables. Editors such as VS Code have formatters that pad the columns for you.
  • After editing, compare the row count in the rendered table with your source. A missing pipe usually shows up as a short row or a shifted column.

Previewing a table

Paste a table into the Markdown Preview to see it rendered next to the source as you type. To get the HTML for it, the Markdown to HTML converter outputs the table, thead and tbody markup, ready to copy.

Both tools render basic pipe tables, and bold, italic, inline code and links work inside cells. Their table support is simpler than GitHub's, so note the differences:

  • Every row must start and end with a pipe. Rows without outer pipes are shown as plain text.
  • Colons in the delimiter row are accepted, but alignment is not applied to the output.
  • An escaped pipe is not recognized and splits the cell in two.
  • A <br> tag is displayed as text, not as a line break.
  • Short rows are not padded with empty cells.

That makes them a good fit for checking structure, such as whether every row has the right number of cells. For alignment, escapes and line breaks, confirm the result on the platform where the table will be published.

Try it

Open the Markdown Preview, type a header row, a delimiter row and a few data rows with a pipe at each end, and watch the table render. Then paste the same source into the Markdown to HTML converter to copy clean table markup.

Tools in this guide

Frequently asked questions

How do I create a table in Markdown?

Write a header row with cells separated by pipes, then a delimiter row with at least three hyphens per column, then one line per data row. Put a blank line before the table. The columns do not need to line up in the source.

How do I center a column in a Markdown table?

Add a colon to both ends of that column's hyphens in the delimiter row, as in :---: for center. A colon on the left only gives left alignment and a colon on the right only gives right alignment.

How do I put a pipe character inside a Markdown table cell?

Escape it with a backslash, written as a backslash followed by the pipe. In GitHub Flavored Markdown this is required even inside inline code. Where HTML is allowed, the entity &#124; also produces a literal pipe.

Can a Markdown table cell have multiple lines?

Not in the Markdown source: each table row must be a single line. To break a line inside a cell, use the HTML tag <br> where the renderer allows HTML. For lists or code blocks in cells, write an HTML table.

More text guides

JSON Formatter
Developer · Format, validate and minify JSON with syntax highlighting.
↵
Base64 Encode / Decode
Developer · Encode text to Base64 or decode Base64 back to plain text.
↵
URL Encoder / Decoder
Developer · Encode or decode URL components and query strings.
↵
Hash Generator
Developer · Generate MD5, SHA-1, SHA-256 and SHA-512 hashes.
↵
UUID Generator
Developer · Generate UUIDs v4 (random) in bulk with one click.
↵
Regex Tester
Developer · Test regular expressions against text with live match highlighting.
↵
Word Counter
Text · Count words, characters, sentences, paragraphs and reading time.
↵
Case Converter
Text · Convert text between UPPER, lower, Title, camelCase, snake_case and more.
↵
List Sorter
Text · Sort, reverse, deduplicate and shuffle lists of text.
↵
Markdown Preview
Text · Write Markdown and see a live rendered preview side by side.
↵
Percentage Calculator
Numbers · Calculate percentages, increases, decreases and what % one number is of another.
↵
Color Converter
Colors · Convert colors between HEX, RGB, HSL and HSV instantly.
↵
Snake
Arcade · Eat food, grow longer, don't hit the walls. A timeless classic.
↵
2048
Puzzle · Slide tiles and combine them to reach the legendary 2048 tile.
↵
Word Grid
Puzzle · Guess the hidden five letter word in six tries using color clues.
↵
Sudoku
Puzzle · Fill the 9x9 grid with logic. Four difficulties from easy to expert.
↵
Minesweeper
Strategy · Use number clues to clear the minefield. Classic logic, three levels.
↵
Breakout
Arcade · Smash every brick with paddle and ball. Power-ups, combos, endless levels.
↵
Typing Practice
Casual · Build your WPM and accuracy with timed drills from 30 seconds to 5 minutes. Find your weak keys.
↵
TypeRunner
Arcade · Multiplayer typing race. Race friends by link, beat computer runners, or chase your own ghost.
↵
Typing Blocks
Arcade · Type each word before its wooden block lands. Miss, and the pile climbs toward the line.
↵
Bubble Shooter
Arcade · Aim, bank shots off the walls, and pop groups of three or more bubbles.
↵
Road Rush
Arcade · Race seven rivals through traffic and punch your way to the front.
↵