Here is the checklist I actually use, in the order that catches the most cases first.

1. The delimiter row does not match the header

Every GFM table needs a delimiter row (| --- | --- |) with the same number of cells as the header row. If the counts differ, the spec says the table is not recognized at all — which is why you get raw text instead of a slightly-wrong table.

| Name | Role |          <- 2 columns
| --- | --- | --- |      <- 3 columns: whole table renders as text

Count the pipes in both rows first. This one mistake explains most "my table renders as plain text" cases.

By the way: the delimiter cells only need one hyphen each per the spec. The "you need at least three dashes" advice you see in old forum answers is folklore — three hyphens are fine for readability, but not required.

2. No blank line before the table

GFM tables interrupt a paragraph in some renderers but not in others. The portable fix is boring: always leave one empty line between your text and the table.

3. A raw pipe inside a cell

A literal | inside cell content splits the cell. Escape it as \|:

| Command | Meaning |
| --- | --- |
| a \| b | pipe a into b |

4. Code spans do not protect pipes

This one surprises people: wrapping a pipe in backticks does not stop it from splitting the cell. Cell boundaries are parsed before inline code, so `a | b` still breaks into two cells. You need \| even inside backticks.

5. Line breaks inside a cell

A literal newline ends the row — there is no multi-line cell in GFM. Use <br> where the platform allows inline HTML, or restructure the data so each row fits on one line.

6. Your renderer does not do tables at all

Tables are a GFM extension, not core Markdown. The CommonMark spec has no table syntax, so a strict CommonMark renderer (some static site generators, comment systems, and chat apps) will show your pipes as plain text no matter how correct they are. Check what dialect your platform renders before debugging your syntax.

7. Invisible characters from copy-paste

Tables assembled from copied content sometimes carry full-width pipes (｜ from CJK input methods), non-breaking spaces, or smart quotes. They look identical on screen and break the parse. Retype the pipes if a table refuses to work and everything else checks out.

When fixing is slower than rebuilding

If a table came from a spreadsheet, a CSV export, or an API response, hand-repairing pipes is usually slower than regenerating the table. I built a CSV-to-Markdown-table converter for exactly this: paste CSV, get a correctly aligned GFM table. It runs 100% in your browser — nothing is uploaded, which matters when the data is an internal export.

Full disclosure: FormatArc is my own project. The checklist above works regardless of what tool you rebuild with.

The 60-second version

1. Header and delimiter row: same cell count?
2. Blank line before the table?
3. Raw | in a cell → \|
4. Pipes in code spans → still \|
5. Newline in a cell → <br> or restructure
6. Does your renderer support GFM tables at all?
7. Full-width ｜ or invisible characters from copy-paste?

If all seven pass and it still breaks, the problem is almost always the platform, not your Markdown.