Why Markdown Tables Aren't in the CommonMark Spec, and How Renderers Filled the Gap

Paste a markdown table into the CommonMark playground at spec.commonmark.org. Pipes, separator row, alignment colons, the whole thing. The renderer returns a wall of literal pipe characters wrapped in a <p> tag. No headers, no rows, no alignment. The same source pasted into a GitHub README renders cleanly. Pandoc renders it. Obsidian renders it. Discord renders it. CommonMark, the closest thing markdown has to a referee spec, does not.

This is not an oversight. CommonMark deliberately excludes tables, alongside footnotes, task lists, and a handful of other features most users assume are "standard markdown." It's intentional and load-bearing. What followed is a quiet fragmentation of table syntax across at least five competing dialects, each with its own rules for alignment, escaping, and cell structure, and each rendering slightly different output from the same source.

The Original Markdown Spec Had No Tables

John Gruber published Markdown in March 2004. Aaron Swartz collaborated on the syntax. The original spec at daringfireball.net describes paragraphs, headings, lists, blockquotes, code blocks, links, images, and inline emphasis. That is the entire feature set. Tables are not mentioned. Gruber has been consistent over two decades that he does not consider tables part of Markdown.

The omission was defensible in 2004. The web was still moving from <table>-for-layout to CSS layouts, and the kinds of plain-text writing Markdown was designed for, like blog posts, README files, and emails, rarely needed tables. When tables were needed, the escape hatch was inline HTML, which Markdown passes through untouched. You could always write a literal <table> in your markdown source.

That answer satisfied no one. Writers wanted tables. The first extension appeared within months.

MultiMarkdown Wrote the Pipe Table Syntax First

Fletcher Penney released MultiMarkdown in 2005, less than a year after the original spec. MultiMarkdown's goal was to add the features Gruber had left out: tables, footnotes, citations, definition lists, and metadata blocks. The syntax Penney chose for tables, pipe characters separating cells and hyphens for the header separator row, became the basis for everything that followed.

The original MultiMarkdown table looked exactly like a modern GFM table:

| Header 1 | Header 2 |
|----------|----------|
| cell 1   | cell 2   |

Penney's reasoning was visual. A writer composing the table in a plain-text editor could see what the rendered output would roughly look like. The pipes were the column dividers. The hyphens were the header underline. The format was its own preview.

MultiMarkdown also introduced the alignment marker syntax: a colon next to a hyphen in the separator row indicated left, right, or center alignment for that column. :--- for left, ---: for right, :---: for center. That syntax is now near-universal across markdown renderers that support tables, but it started in MultiMarkdown.

GFM Made the Pipe Table Look Standard

GitHub Flavored Markdown, known as GFM, was first published as a formal specification in 2017, with the CommonMark Spec serving as its base. GFM is, formally, a strict superset of CommonMark with five extensions: tables, task list items, strikethrough, autolinks, and disallowed raw HTML. The table syntax was lifted directly from MultiMarkdown: pipes, separator row, optional alignment colons.

The reason GFM tables feel canonical is volume. GitHub renders billions of README files, issues, pull requests, and comments per year. When developers learn markdown, they learn it by reading what renders on GitHub. The pipe table syntax has been the GitHub default for over a decade; the 2017 spec just codified what was already universal.

The GFM specification is precise about the rules. A table needs a header row, a delimiter row of hyphens (with optional alignment colons), and any number of data rows. Cells are separated by pipes. Leading and trailing pipes are optional. Inline markdown inside cells is allowed, but block-level constructs (paragraphs, lists, headings) are not. Cell content cannot contain literal pipe characters unless escaped with a backslash.

That last rule, pipe escaping, is one of the quiet sources of cross-renderer inconsistency. GFM requires \| to embed a literal pipe in a cell. Some renderers treat | (the HTML entity) as equivalent. Others accept neither.

Pandoc Took the Opposite Path with Grid Tables

John MacFarlane released Pandoc in 2006. MacFarlane also leads CommonMark development, which makes Pandoc's approach to tables instructive: even the person responsible for the CommonMark spec implements multiple table syntaxes in his own tool, because pipe tables are not expressive enough for the documents Pandoc was built to handle.

Pandoc supports four table syntaxes. Pipe tables work the same as GFM. Simple tables use spaces to define columns and dashes only for the separator row. Multiline tables extend simple tables to allow line breaks within a cell. Grid tables use ASCII-art box-drawing characters (plus signs at corners, hyphens for horizontal lines, pipes for vertical lines) to fully delimit every cell.

+---------+---------+
| Header  | Header  |
+=========+=========+
| Cell    | Cell    |
| line 2  | line 2  |
+---------+---------+

Grid tables can contain block-level content. A cell can hold a paragraph, a list, a code block, or even a nested table. Pipe tables cannot. For technical writers producing PDFs or e-books from markdown, grid tables are the only option that handles complex cells.

The cost of grid tables is the writing experience. Composing one by hand is tedious. The visual structure has to be maintained character by character. Most editors do not auto-format them, and the few that do disagree on column-width rules. Grid tables are powerful, rare, and almost never seen outside academic publishing toolchains.

What Counts as a Valid Table Depends on Where You're Pasting

The fragmentation gets practical when the same markdown source moves between systems. A pipe table written for GFM may render fine on GitHub, fine in Obsidian, fine in VS Code's preview, and as a literal block of pipe characters in a CommonMark-strict renderer like the reference implementation at spec.commonmark.org. A grid table written for Pandoc renders as a code block almost everywhere except Pandoc itself.

The alignment markers behave similarly. GFM honors :---: for center alignment. MultiMarkdown honors it. Pandoc honors it in pipe tables but uses different syntax in grid tables. Some markdown-it plugins ignore alignment entirely and let CSS handle it. Whether your column is centered depends on the renderer, not just the source.

Cell width is the trickier inconsistency. Most renderers ignore the actual widths in the source. They parse the table into rows and cells, then re-render with their own CSS. But the source still needs to be readable in a plain-text editor, which means a human or a formatter has to maintain monospace alignment for the writer's sanity. That alignment is purely cosmetic at render time. It is essential at edit time.

Five Renderers, Five Sets of Rules

The CommonMark row is the surprise to most writers. Strict CommonMark has no table support whatsoever. Every renderer that handles tables is, technically, implementing a non-standard extension.

Where the Inconsistency Bites You

The fragmentation is usually invisible because most people write markdown for one destination at a time. README files target GitHub. Documentation sites target their site generator. Notes target Obsidian. The renderer is fixed, and the syntax that works there works.

The pain shows up at migrations. Moving documentation from a GFM-rendered wiki to a Pandoc-rendered PDF pipeline means re-checking every table for cells with line breaks, pipes in content, or block-level elements that worked in one renderer and break in the other. Pulling a markdown post from Obsidian into a Hugo site can change which alignment markers are honored. Authoring a blog in MultiMarkdown and publishing through CommonMark drops every table to plain pipe-and-hyphen text.

Width handling adds its own layer. The renderer does not care about width, but the editor does. A table that looks aligned in VS Code may look misaligned in a different monospace font where character glyphs render at slightly different widths. CJK characters, emoji, and combining marks compound the problem because their display widths in monospace fonts are not consistent across systems. The source text can be correctly aligned for one editor and visually wrong in another.

If you're writing markdown tables that need to look right in the source, for code review, for collaborative editing, for any case where a human reads the raw text, the formatter you reach for matters more than the renderer. A formatter that respects Unicode East Asian Width and applies consistent column padding will produce source that aligns in any monospace context, regardless of which renderer eventually parses it. Pipefmt is one option for that, free in the browser, with a live preview that shows you exactly what the source will look like after formatting. The renderer fragmentation is not going away. The least you can do is make sure the source reads cleanly in plain text.