How To Format Markdown Tables

The pipe-and-dash skeleton

Markdown tables look deceptively simple—three pipes and a dashed separator—but the moment you try to align columns, escape pipes inside cell content, or move a table between GitHub Flavored Markdown and CommonMark, the cracks show. A table that renders beautifully on GitHub can break on a static site generator, and a table that copies cleanly from a spreadsheet can arrive with ragged pipes and missing headers. The spec also refuses to standardize tables at the CommonMark level, which means every renderer implements them slightly differently. Getting the syntax right once saves hours of manual fiddling across README files, documentation sites, and blog posts. This guide covers pipe syntax, header separators, alignment, escaping special characters, GFM versus CommonMark differences, and the fastest way to generate valid tables from existing data.

Column alignment with colons

Every Markdown table is built from three row types: a header row, a separator row of dashes, and one or more data rows. The leading and trailing pipes are optional in most renderers, but always including them makes the source easier to read and less prone to parser ambiguity when a cell starts with a character the renderer treats as meaningful.

GFM versus CommonMark

The separator row needs at least three dashes per column in most strict parsers, although GFM accepts a single dash. Pad the dashes to match the header width if you want the source to line up visually—the rendered output is identical either way.

Escaping pipes inside cells

Alignment is controlled by where you place colons in the separator row. A colon on the left means left-aligned, a colon on the right means right-aligned, and colons on both sides mean center-aligned. Without any colon, most renderers default to left alignment, but some respect the renderer’s CSS instead, so always be explicit when alignment matters.

Inline formatting inside cells

CommonMark’s base specification does not define tables at all. Tables are a GitHub Flavored Markdown extension, later adopted by other flavors like MultiMarkdown and Pandoc, but each implementation diverges in small ways. GFM requires a header row, GFM rejects tables without a separator row, and GFM allows inline formatting like bold and code inside cells but forbids block elements like nested lists or paragraphs. Pandoc supports pipe tables, grid tables, and multiline tables with different rules for each. When in doubt, write to the GFM spec because it has the widest runtime support across static site generators, documentation tools, and chat platforms.

Handling long content and wrapping

A raw pipe character inside a cell will be interpreted as a column boundary and silently break your table. Escape it with a backslash, or wrap the value in a code span if the content is code-like. HTML entities also work but make the source harder to read.

Generating tables from spreadsheets and CSV

Backticks around the whole cell are the most robust option because the renderer stops parsing table syntax inside a code span. That is also the only way to include a literal backslash without the renderer eating it.

Tables inside lists and blockquotes

Common mistakes

Run the numbers