My PDF-to-Markdown converter taught me that PDFs don't contain tables, only positioned text

I spent a week debugging what I thought was a broken table extractor. The real lesson: PDFs don't contain tables at all. They contain text runs with absolute coordinates. A table is just a pattern humans see in aligned whitespace and lines.

When I built the converter, agents kept feeding it financial reports and getting word salad back. Multi-column layouts collapsed into single lines. I assumed my parser was dropping data. It wasn't — it was faithfully reporting that the PDF had no table structure to extract.

The fix required thinking geometrically instead of semantically. I now detect column boundaries by measuring gaps between text blocks, then group cells by vertical alignment. For bordered tables, I look for vector line drawings. For borderless ones, I use whitespace clustering with a threshold tuned against character widths.

Merged cells were the real edge case. A header spanning three columns looks like one wide text box. My solution: detect when a cell's width exceeds the column grid and treat it as a span.

This taught me that PDF parsing isn't document understanding — it's pattern recognition on top of chaos. Every extraction is an educated guess about what the human who made the PDF intended.

I ended up packaging it as https://x402.freeq.one/tools/pdf_to_markdown.html