PDF → Markdown

Tables are the reason most PDF-to-Markdown conversions look great on page one and fall apart on page four. Prose survives extraction because it is sequential; a table is a two-dimensional object squeezed into a format that only understands lines. This guide explains why pipe tables break during PDF table to Markdown conversion, how three common table types behave differently, and how to repair misaligned columns by hand without rewriting the whole document.

Why PDF tables break in naive conversion

A PDF does not contain tables. It contains drawing instructions: place the glyph "R" at this coordinate, draw a line at that one. Columns and rows are a visual illusion created by alignment. Nothing in the file states that the text on the left belongs to the same row as the text on the right, or that a horizontal rule separates a header from data.

A converter has to reconstruct that grid. It clusters text by x-coordinates to guess columns, by y-coordinates to guess rows, then assigns each text run to a cell. That inference is where errors enter:

• Column drift. A right-aligned number column next to a left-aligned text column produces overlapping clusters, so two columns merge or one splits down the page.
• Wrapped cells. A cell containing three lines of text is treated as three rows, inflating the row count.
• Reading order. Two-column page layouts interleave with tables, splicing body text into table rows.
• Missing rules. Tables with only a header rule, or no rules at all, give the extractor no anchoring geometry.
• Character artifacts. Ligatures, soft hyphens, and non-breaking spaces land inside cells.

These are ambiguities in the source, not simply tool bugs. The practical takeaway: expect to verify and repair table output rather than trust it. If you are new to the conversion step itself, start with this walkthrough of converting a PDF to Markdown.

The GFM constraint

GitHub Flavored Markdown pipe tables are strict and minimal. The header row, the delimiter row, and every body row must contain the same number of columns. There is no colspan, no rowspan, no nested tables, and no true multi-line cells — you simulate a line break with <br>. Any literal pipe inside a cell must be escaped as \|. A converter that emits seven pipes in row one and six in row two has produced something no strict renderer will display correctly; most will drop the table or dump the ragged remainder as plain text.

Three table archetypes, three failure modes

Field tables (key and value)

Invoice details, spec sheets, metadata blocks, and "field: value" panels. Usually two columns, with labels that wrap onto a second line. These convert most reliably. The recurring failure is a wrapped label becoming its own row, which shifts every value below it by one. Repair by joining the wrapped text back into the label cell with <br>, then re-checking that values still line up with their labels.

Comparison tables (feature matrices)

Rows are options, columns are properties, and cells hold checkmarks, short phrases, or deliberate blanks. Three problems dominate. First, merged group headers: a single "Storage" header spanning three subcolumns. GFM cannot express that, so flatten it into compound column names such as Storage (Free), Storage (Pro), and Storage (Team). Second, empty cells that may mean "no" or "unknown" — decide which and mark it explicitly. Third, symbols and icons that extract as garbage; replace them with text or a consistent character.

Return-code and numeric tables

Error code lists, status matrices, pinouts, and constant tables. These are dense, often monospaced, and frequently contain characters that collide with Markdown syntax: pipes, asterisks, underscores, and backticks. An error row like | 0x04 | \*ERR_TIMEOUT\* | Retry the request | needs escaping at every collision point. Numeric tables also expose alignment. GFM's delimiter row accepts colons, so | ---: | right-aligns a column — reapplying alignment after repair is what makes a long numeric table scannable.

Code	Meaning	Action
0x01	Invalid argument	Check the request body
0x04	Timeout	Retry with backoff

Repairing misaligned columns by hand

Work top to bottom and fix one row at a time.

1. Find the first broken row. Count pipe characters per line. The first row whose count differs from the delimiter row is the source of the cascade; rows below it may already be correct but will render wrong until it is fixed.
2. Compare against the source page. Open the PDF side by side and decide whether the row has too many or too few cells, and which cell absorbed or lost content. Do not guess.
3. Repair the row. If a wrapped cell became an extra row, merge it upward and separate the lines with <br>. If two columns merged, split at the original boundary and insert a pipe.
4. Escape in-cell syntax. Convert literal pipes to \| and escape *, _, and backticks so emphasis does not fire inside data.
5. Normalize the delimiter row. One --- segment per header column, with alignment colons where useful.
6. Verify counts. Header, delimiter, and every body row must match. Then preview the rendered output.

Merged cells and other GFM gaps

Because GFM has no spans, three patterns recur:

• Spanning group headers: flatten into compound column names.
• Merged data cells: repeat the value in each affected cell, or keep the extracted data in CSV or HTML if fidelity matters more than portability.
• Multi-line cells: use <br>, or split the table into two tables sharing a key column.

When hand repair is the wrong tool

If the source is a scan — an image PDF with no text layer — no amount of column fixing helps, because the characters themselves are missing or wrong. That case belongs to OCR first, and the table work begins afterward. Review OCR best practices for scanned PDFs before spending time on alignment.

A verification pass that keeps tables honest

Treat tables as a separate review step rather than part of a general read-through:

• Count rows in the Markdown table and compare with the source page. A quick visual count catches silent row loss.
• Spot-check the final row of every table; extraction errors tend to compound toward the bottom of a page.
• Check the first data column for type consistency. If a column should be all numbers and one entry is a word, the column boundary is wrong.
• Render before committing. Obsidian's reading view, Notion, and GitHub's file view use different parsers, and a table that renders in one may not in another.

If you handle tables regularly, standardize the sequence: convert, run the table review, repair, then move on. That pipeline is described in detail in a repeatable PDF to Markdown workflow. For a single document, the free PDF to Markdown converter gives you a text-based starting point in the browser before any manual work.

FAQ

Can any PDF table be converted to Markdown automatically?

No. Text-based PDFs with ruled tables convert well. Tables without rules, spanning headers, or nested layouts usually need a manual pass, and scanned tables need OCR before any structural work. Automatic conversion gets you most of the way; the last part is judgment.

What should I do with a table GFM cannot represent?

Decide what matters more: visual fidelity or portability. If you need to paste into Obsidian, Notion, GitHub, or an LLM prompt, flatten merged cells and group headers, accept repeated values, and keep the pipe table. If fidelity matters, keep the original PDF page as the reference and store the extracted data as CSV or HTML instead.

Why does my table render correctly in the editor but break after export?

Different parsers tolerate different mistakes. Many editors guess at ragged rows and repair them silently; strict GFM parsers do not. If a table looks right in a live preview and wrong in the finished document, count pipes per row — the preview was compensating for a mismatch the final renderer will not fix.