Yes, Markdown supports tables, but only as an extension: the original Markdown syntax had none, and GitHub Flavored Markdown (GFM) is where the common pipe table comes from. When a Markdown table is not rendering, the cause is almost always one of four things: the renderer doesn't have tables turned on, the delimiter row is missing, the column counts don't match, or the table sits right under a paragraph without a blank line.
Are tables part of standard Markdown?
Tables are not part of the original Markdown syntax; they are extended syntax that each renderer may or may not support. The GFM spec titles its table section "Tables (extension)" and says GFM enables that extension on top of CommonMark. The Markdown Guide puts tables in its extended syntax page and warns that not all Markdown applications support extended elements.
That's why the same file can look perfect on GitHub and broken somewhere else. The authors of remark-gfm say users frequently believe tables are part of normal markdown. They aren't, and a renderer that sticks to the core syntax will print your pipes as text.
How the pipe table syntax works
A pipe table is a header row, a delimiter row of hyphens, and zero or more data rows, with cells split by pipes. Here's the smallest table that works in GFM:
| Format | Use it for |
| ------ | ------------ |
| JSON | API payloads |
| YAML | Config files |
A few rules from the spec matter in practice:
- Outer pipes are optional but recommended for readability. The Markdown Guide adds them "for compatibility", so keep them.
- Cell widths don't have to line up. Spaces around cell content are trimmed, so
|a|b|and a neatly padded table render the same. - Alignment goes in the delimiter row.
:---is left,---:is right, and:---:is centered. - Inline formatting works in cells: links,
codeand emphasis. Headings, lists, blockquotes and images don't.
Why is my Markdown table not rendering? A symptom-to-fix table
A Markdown table that fails to render shows a specific symptom, and each symptom maps to one rule in the spec. Find what you see in the left column.
| What you see | Likely cause | Fix |
|---|---|---|
| Raw pipes and dashes as one paragraph | Renderer has no table support, or header and delimiter cell counts differ | Turn on the table extension; make both rows the same width |
| Raw pipes only under a sentence | No blank line between the paragraph and the table | Add an empty line above the header row |
| A stray line shows up as an extra row | Text right after the table, with no blank line | Add an empty line after the last row |
| Columns split in the wrong place | An unescaped pipe inside a cell | Write it as | |
| Last cells look empty | That row has fewer cells than the header | Fill the row; GFM inserts empty cells for missing ones |
| Extra cells disappear | That row has more cells than the header | GFM ignores the excess, so add a header column |
The column count rule surprises people the most. The GitHub Flavored Markdown spec states that the header row must match the delimiter row in the number of cells, or the table will not be recognized. Its own example with two headers and one delimiter cell comes out as a plain paragraph.
A real broken example
Here's a table I see pasted into READMEs all the time. It fails twice.
Supported formats:
| Format | Extension | Notes |
| --- | --- |
| JSON | .json | Strict |
The header has three cells and the delimiter row has two, so GFM refuses to build a table. Even with that fixed, the header row follows "Supported formats:" with no blank line, so many renderers read it as part of that paragraph. Add a third --- cell and an empty line under the sentence, and it renders.
Check whether your renderer supports tables
Whether a Markdown table renders depends on the parser behind the page, and each one has its own switch. If the syntax is right and you still see pipes, look here:
- remark and react-markdown: add the remark-gfm plugin. It enables the GFM extensions, tables included.
- marked: the
gfmoption defaults totrue. Butpedantic: trueturns off and overridesgfm, so check that it isn't set. - Hugo: the Goldmark table extension is on by default. If someone set
table = falseundermarkup.goldmark.extensions, set it back totrue. - Python-Markdown: the Tables extension ships with the library but you have to enable it. It uses PHP Markdown Extra syntax, which is close to GFM.
What Markdown tables can't do
Pipe tables can't hold block content: the GFM spec says block-level elements cannot be inserted in a table. That rules out lists, multiple paragraphs, fenced code blocks and headings inside a cell. There's also no syntax for merged cells.
The Markdown Guide suggests HTML for line breaks and lists inside cells, and the HTML character code | when you need a literal pipe. When a table needs merged cells or rich content, write it in HTML from the start:
<table>
<tr><th>Format</th><th>Notes</th></tr>
<tr><td>JSON</td><td>Strict<br>No comments</td></tr>
</table>
Raw HTML only works where the renderer lets it through, so test it on the target site. If you're building the page yourself, our guide to displaying Markdown in HTML covers sanitizing that output.
My take on writing tables that render everywhere
Write every table in strict GFM form: outer pipes on every row, a blank line above and below, a delimiter cell for every header, and no pipes inside cells unless escaped. That style renders in GitHub, Hugo and remark-based sites, and it still reads fine as plain text.
Past a few columns, stop hand-typing pipes. If the data starts as JSON, convert JSON to CSV and generate the table from that. You'll make fewer mistakes.
A limitation of OnlineViewer's Markdown preview
OnlineViewer's Markdown preview uses a small built-in renderer, not a full CommonMark or GFM parser. It handles headings, bold and italic, inline and fenced code, links, images, blockquotes, lists, horizontal rules and paragraphs. Pipe tables aren't on that list, so it can't tell you whether a table renders.
Preview the table where it'll be published instead: a GitHub issue draft or your site's local dev server. If you've moved a table to HTML, check that HTML, and a tool like Prettier or an online formatter can tidy it first.
FAQ
Are tables part of standard Markdown?
No. Tables are extended syntax. The GitHub Flavored Markdown spec lists them as an extension, and the Markdown Guide notes that not all Markdown applications support extended syntax.
Why does my Markdown table show as plain text with pipes?
Usually the renderer has no table support turned on, the delimiter row is missing, or the header row and delimiter row have a different number of cells. In GFM, a count mismatch means the table is not recognized at all.
How do I put a pipe character inside a table cell?
Escape it with a backslash, as in a|b. The GFM spec says the escape works inside code spans too. The Markdown Guide also suggests the HTML character code |.
Can I merge cells or put a list inside a Markdown table?
Not with pipe table syntax. The GFM spec says block-level elements cannot go in a table. For lists, line breaks or complex layouts, use HTML inside the cell or write the whole table in HTML.