Guides to converting PDFs well
Converting a PDF is easy. Getting a result you can rely on takes knowing what the format does and does not record, where every converter has to guess, and what to check before you trust the output. These guides cover the questions that come up most, and none of them resolves to “so use our converter”.
Why converting a PDF loses structure, and what to do about it
PDFs store positioned glyphs, not document structure. Understanding that explains every conversion error you will ever see.
8 minute read
The Markdown you get back, and how to clean it up
What the converter emits, which Markdown features survive the trip, and the handful of tidy-up passes worth doing every time.
7 minute read
Importing PDFs into an Obsidian vault without making a mess
Turning a folder of PDFs into notes that Obsidian's outline, search and graph can actually use.
7 minute read
Preparing PDFs for LLMs and retrieval pipelines
Why Markdown outperforms raw extracted text in retrieval pipelines, and how to chunk it without destroying what makes it work.
9 minute read
Two-column PDFs: diagnosing and fixing reading order
Why a two-column paper sometimes converts into alternating half-sentences, and what to do when it does.
8 minute read
Repairing tables that did not survive conversion
Why merged and wrapped cells break table detection, and how to repair the four failure modes in the output.
8 minute read
What text recognition can and cannot recover from a scan
Recognition turns pixels into positioned words with confidence scores. Knowing what that means explains which scans work.
9 minute read
DOCX or PDF: which source converts better, and why
One format states its structure and the other makes you infer it. That single difference decides most of the outcome.
7 minute read
Converting a thesis or a long report, chapter by chapter
A three-hundred-page document is not a big version of a short one. It fails in its own ways, and splitting first avoids most of them.
8 minute read
Turning a PDF bibliography into linked notes
Reference lists convert badly for a specific structural reason. Here is the repair, and the part worth scripting.
7 minute read
What Obsidian, Notion and Logseq each need from Markdown
Three tools, three dialects. What each does with a converted file, and the one shape that suits all of them.
8 minute read
Chunking converted documents for retrieval
Chunk on the heading ladder rather than on character counts, and know what to do when conversion did not produce one.
9 minute read
The one idea underneath all of them
A PDF does not contain headings, paragraphs, lists or tables. It contains glyphs at coordinates. The structure that produced the layout was used to compute those positions and then discarded, which means converting a PDF to Markdown is not extraction but inference: reading the geometry back and deducing what structure would have produced it.
Every converter does this, ours included, and no converter can do better than infer — the answer is genuinely not in the file. Once that is clear, the errors stop looking arbitrary. A heading that came out as a paragraph was styled by weight rather than size. A table that collapsed had merged cells. A page that reads as nonsense had two columns. Each failure traces back to a rule, and a rule you know about is one you can work around.
The guides here fall into three groups. Some explain the inference itself and the failure modes that follow from it — lost structure, interleaved columns, collapsed tables, and what recognition can recover when there is no text to read at all. Some are about the file you get back and the edits worth making before you keep it. The rest are about destinations — a note vault, a retrieval pipeline, a bibliography, a document long enough that it needs taking apart first — which place quite different demands on the same Markdown.