A Repair Workflow for Broken Markdown Tables

Broken Markdown tables are easier to fix when you debug them in a consistent order. If you start by changing spacing randomly, you can make the table harder to read without addressing the real problem.

This workflow is for tables that render oddly, convert with warnings, shift columns, or swallow text after the table.

Step 1: Find the separator row

A Markdown table needs a separator row:

| Name | Status |
|---|---|
| Alex | Ready |

The separator row contains dashes and optional colons. These are valid:

|---|---|
|:---|---:|
|:---:|---|

This is not a separator row:

| === | === |

If the separator is invalid, a converter should treat the text as normal Markdown, not as a table.

Step 2: Count the header cells

The header decides the expected shape:

| Name | Role | Status |
|---|---|---|

That table expects three cells per body row. A row with two cells can still be converted with a blank missing value, but it should be reviewed:

| Sam | Reviewer |

If the missing value is meaningful, fill it in explicitly:

| Sam | Reviewer | Pending |

Explicit cells are easier for future editors to maintain.

Step 3: Escape literal pipes

If a value contains a literal pipe, escape it:

| Pattern | Meaning |
|---|---|
| success \| warning | Either status |

Inline code can also contain pipes:

| Command |
|---|
| `cat file | grep error` |

The converter should keep those pipes inside the cell. If the row suddenly has extra columns, check for unescaped pipes first.

Step 4: Protect code blocks

Fenced code should stay outside table parsing:

```sh
cat logs.txt | grep error
```

If a document has both tables and shell commands, keep fences intact. Removing fences can make a command look like a table row.

Step 5: Mark the end of the table

If a sentence with a pipe follows a table, add a blank line:

| Key | Value |
|---|---|
| A | 1 |

Use A | B for fallback.

The blank line tells readers and tools that the table is finished. Without it, some parsers may try to treat the sentence as another row.

Step 6: Convert and inspect health

After repairing the source, convert it and check:

Check	Why it matters
Table count	Confirms the right blocks were parsed
Row count	Catches swallowed prose
Column count	Shows unexpected splits
Max line width	Predicts wrapping
Diagnostics	Points to source rows

If the output is wider than 80 columns, do not force it. Shorten cells, split the table, or use Simple text.

A repair example

Original:

| Key | Value |
| === | === |
| Status | success | warning |
Use A | B for fallback.

Repaired:

| Key | Value |
|---|---|
| Status | success \| warning |

Use A | B for fallback.

The repaired version has a valid separator, a literal pipe inside the cell, and a clear boundary after the table. That is the kind of source that converts predictably.