How to repair broken Markdown tables in 30 seconds
Tables are the single thing AI assistants get wrong the most often. They look fine in chat — because the chat UI rounds off the rough edges as it renders — and they fall apart the moment you try to do something real with the document. Here's what's actually wrong with the table, and the fastest way to fix it.
What a broken Markdown table looks like
Here's a table ChatGPT might produce. It looks plausible:
| Metric | Q1 | Q2 | Q3
| ------ | -- | --
| Signups | 1,200 | 2,100 | 3,400
| Activations | 800 | 1,500
| ARR ($) | 14k | 27k | 41k | 60kIt is, however, completely broken. Three different things are wrong with it.
The three things that almost always break
1. The header row is missing a trailing pipe. "Q3" at the end of row one has no closing |. Some renderers are forgiving about this; many aren't. The DOCX and PDF exporters that respect the spec aren't.
2. The delimiter row has the wrong number of cells. The header has four columns. The delimiter row (--- | ---) has three. A strict parser sees "header has four columns, body claims three" and either gives up or silently drops the fourth column.
3. Body rows have inconsistent column counts. Row 3 has three values, row 4 has two, row 5 has four. None of them match the header. Renderers handle this in different ways: some pad with empty cells, some truncate, some refuse.
The 30-second manual fix
To repair this by hand:
- Count the header columns by counting
|characters and subtracting one. (Or just look.) - Make the delimiter row have the same number of
---cells. - Either pad each body row with empty cells (
| |) or truncate it to match. - Make sure every row starts and ends with
|.
For one table that's a minute. For a document with five tables you didn't write yourself, it's a small bad afternoon.
What automatic repair actually does
The version of this in Markdown Tidy does six things in one pass:
- Counts columns from the header row.
- Fixes or inserts a delimiter row that matches.
- Pads short rows with empty cells.
- Truncates over-long rows (and flags them so you can review).
- Adds missing leading or trailing pipes.
- Escapes any literal pipe characters that appear inside cell content.
None of this is clever. It's just mechanical work the human shouldn't have to do.
Edge cases worth knowing about
Inline code inside cells. Backtick code inside a table cell is supported but fragile. If the code contains a pipe character (|), most parsers think it ends the cell. The fix is to escape it: \|. Repair does this automatically.
Very wide tables. A table with eight columns that fits in your chat window will not fit on a portrait PDF page. The cleanup itself can't fix this — but switching to a landscape-oriented design system, or splitting the table, can. Watch out for this when exporting.
Tables that should not be tables. AI assistants love to put two-column key/value lists into table syntax. Sometimes a definition list (Term: value) reads better and survives Markdown to DOCX more cleanly. If the "table" has only two columns and one row per fact, consider switching.
Related reading: Why ChatGPT Markdown breaks in Google Docs · The AI-generated Markdown cleanup checklist