Repairing tables that did not survive conversion
Last reviewed
Tables are where conversion most often visibly fails, and the reason is structural rather than incidental. A PDF records no table. It records some text at some positions, and the fact that a human sees a table is a property of the human.
So table detection is a guess about alignment, and the guess is made under rules you can learn. Once you know them, a broken table tells you which rule it broke, and that tells you how to fix it.
8 minute read
What has to be true for a table to be found
A run of consecutive lines becomes a table only when all of the following hold. Each is measured against the body-text height, so they scale with the document rather than assuming a font size.
| Cell boundary | A horizontal gap wider than 1.5 body heights |
|---|---|
| Minimum size | At least 2 rows, each with at least 2 cells |
| Column count | Between 2 and 12 detected columns |
| Alignment | At least 2 columns appear on 60% or more of the rows |
| Cell length | Mean cell length of 60 characters or less |
| Continuity | Breaks at a page change, or a vertical gap over 3 body heights |
The last two rules are the interesting ones
The alignment rule is what separates a table from justified prose. Justified text produces wide horizontal gaps too — that is what justification is — but it never produces them in the same place line after line. Requiring columns to recur across most rows is precisely the test that prose fails and a table passes.
The mean cell length rule is a second guard on the same problem. A block that satisfies every geometric test but whose cells average a hundred characters is far more likely to be a two-column layout, or a definition list, or an indented quotation, than a table. Rendering it as a table would produce something technically valid and completely unreadable, so it is rejected and rendered as text.
Failure one: merged cells
This is the most common by a wide margin, and it follows directly from the alignment rule. A merged cell spans a position no other row uses. Its neighbours shift. The columns stop recurring, the sixty per cent test fails, and the whole block stops being a table.
The tell is that the table did not come out slightly wrong — it came out as paragraphs. If a table in your PDF has a header spanning two columns, or a category label spanning several rows, expect this.
Failure two: a cell whose text wraps
A cell containing text long enough to wrap onto a second line is, geometrically, two rows: one complete, and one with content in a single column and nothing in the others.
The result is a table with a ragged row in the middle of it, and because a GFM pipe table takes its column count from the separator row, a ragged row is not just untidy — the table is invalid and renders as literal text with pipes in it.
| Component | Status | Notes |
| --- | --- | --- |
| Ingest worker | Healthy | Restarted after the |
| deploy on Tuesday |
| Index builder | Degraded | Backlog of 4 hours |Repairing a ragged table
Fold the orphaned line back into the cell it belongs to, and pad any row that is genuinely short with empty cells. Every row must carry the same number of pipes as the separator row — that is the only rule the format has.
Where a cell genuinely needs two lines, a line break tag inside the cell is the standard way to express it, and every renderer that supports GFM tables supports it.
| Component | Status | Notes |
| --- | --- | --- |
| Ingest worker | Healthy | Restarted after the deploy on Tuesday |
| Index builder | Degraded | Backlog of 4 hours |
| Query API | Healthy | |Failure three: the table that spans a page break
Table detection stops at a page boundary, deliberately. Across a break the geometry says nothing useful: the last row of page four and the first row of page five are hundreds of points apart in a coordinate system that resets.
A table running over three pages therefore converts as three tables, each with the first row of that page promoted to a header. The repair is mechanical: delete the two spurious header and separator pairs, and check that the column count agreed across all three. If it did not, the pages had different alignment and the fragments need reconciling by hand.
Failure four: prose that became a table
The rarer direction, and the more confusing one to look at. A block of text with strong repeated indentation — a two-column term-and-definition list, an aligned code sample, a poem set in columns — can satisfy every rule and come out as a table.
It is usually obvious because the cells are long and the header is nonsense, since the first row is always taken as the header. The fix is to delete the pipes and reflow the text, and there is nothing subtle about it.
If a document is mostly this kind of block, converting with table detection turned off produces a much better starting point than repairing every false table afterwards.
When to stop repairing and retype
There is a threshold past which repair is the slower option, and people generally cross it long before they admit it.
A table that lost its column alignment entirely — where the cells are present but distributed wrongly across the columns — is faster to retype from the PDF than to reconstruct from the Markdown, because retyping needs one reading of the original and repair needs a comparison of both on every cell. As a rule of thumb, if more than a quarter of the cells are in the wrong column, retype.
Two things make the decision easier. Converting the table on its own, from a single-page extract of the PDF, very often succeeds where it failed inside a sixty-page document, because the body-text height is computed from that page rather than the whole file. And a numeric table is worth checking cell by cell whichever route you take: a table that looks right and has two numbers in the wrong column is the failure that survives review.