GFM Pipe Tables: The Rules That Decide Whether It Renders
A pipe table renders only when a header row is followed immediately by a separator row with the same number of cells. Everything else is plain text. The table formatter applies the same test before touching anything.
The structure
| Name | Role |
| :---- | ---: |
| Alice | Lead |- The separator cells are dashes with optional colons.
:--aligns left,:-:centres,--:aligns right. - Leading and trailing pipes are optional in GFM, but a line with no pipe at all ends the table.
- Padding never changes the rendered result. It only makes the source readable and diffs small.
What the formatter does and does not change
| Case | Behaviour |
|---|---|
| Column narrower than its widest cell | Padded; the minimum column width is 3 so the separator stays valid. |
| Body row with fewer cells than the header | Padded with empty cells, which is what GFM renders. |
| Body row with more cells than the header | Table left exactly as written and counted as skipped. GFM drops the extra cells; widening the table would change that. |
| Table inside a fenced code block | Untouched. |
| inside a cell | Kept as an escaped pipe, not treated as a column break. |
Pipes inside code spans
In GFM an unescaped | splits the cell even inside backticks. Write \| there. This is the usual reason a table with a command like a | b in it renders with an extra column.
Width
The formatter counts characters by code point. East-Asian wide characters and many emoji occupy two columns in a monospace font, so a table containing them will look misaligned in the source even though it renders correctly.