PDF to Markdown: a quality-first guide

Start by identifying what kind of PDF you have

Conversion quality is decided before you press convert. A PDF either carries a text layer with coordinates, or it carries pictures of text, or it mixes both — and each case needs a different path. Guessing wrong is how you end up with Markdown that looks fine and quietly lost half a page.

A ten-second test

• Try to select a sentence. If the cursor selects a run of words, there is a text layer to extract.
• Search for a word you can see. No match on a visible word means the page is an image, or the font has a broken character map — both need OCR.
• Check pages in the middle, not the cover. Annual reports and manuals routinely embed scanned exhibits inside an otherwise digital file.
• Look for two columns, sidebars, or rotated tables. Text exists, but the order it is stored in is often not the order a human reads it.

Route page by page rather than document by document. Sending 200 pages through an expensive model because four of them are scanned is the most common way to overpay for a conversion.

What actually breaks in a PDF to Markdown conversion

These are the failure modes worth checking for, in the order they cost people the most time. Each one is visible in the samples on the homepage.

• Reading order. Two-column papers are often stored column-fragment by column-fragment. A naive extractor interleaves the columns, so sentences from the left column continue into the right one. The arXiv paper sample is the standard test case.
• Repeated page furniture. Running headers, footers, page numbers, watermarks, and licence stamps are ordinary text to an extractor. They land in the middle of your Markdown — the Chinese technical report repeats a page marker on every page, and the arXiv paper carries a reproduction notice above its own title.
• Tables. A PDF table is not data. It is text at coordinates with lines drawn near it. Merged cells collapse, multi-line cells split into separate rows, and a table continuing across a page break becomes two unrelated tables. The financial statement sample has all three.
• Formulas. Inline math usually survives as mangled characters — superscripts flatten, Greek letters drop, and spacing disappears. If the formulas matter, you need a parser that emits LaTeX, not a text extractor.
• Footnotes and captions. They sit outside the main text flow, so they either vanish or get spliced into the middle of a paragraph.
• CJK text. Chinese, Japanese, and Korean PDFs add full-width punctuation, missing word boundaries, and vertical layouts. Extractors tuned on English text insert spaces between every character or drop punctuation entirely.

Verify the output instead of skimming it

Plausible Markdown is the trap. Output that reads smoothly can still be missing a footnote, a table row, or an entire column. A five-minute pass catches nearly all of it:

1. Compare the first and last block of each page against the PDF. Reading-order bugs show up at page and column boundaries first.
2. Search the Markdown for three words you can see in figures, captions, and footnotes. Missing hits tell you what class of content was dropped.
3. Check the heading outline. If a 30-page manual produced two headings, heading detection failed and your Markdown has no structure to navigate.
4. Spot-check one table per document — specifically one with merged cells or one that crosses a page break.
5. Compare rough word counts per page. A page that produced far less text than its neighbours is usually a scan, a figure-heavy page, or an encoding failure.

This only works if the converter keeps the evidence. Every block should carry its page number, bounding box, reading order, extraction method, and a confidence value, so a suspicious line can be traced back to the exact spot on the page instead of re-read against the original by hand.

Tables: choose a strategy before you convert

There is no single correct Markdown representation of a PDF table, so decide what the table is for. GitHub-flavoured Markdown tables are readable but cannot express merged cells; HTML keeps the layout but is awkward to edit; JSON keeps the data but is not a document.

{
  "type": "table",
  "page": 9,
  "bbox": { "x": 72, "y": 318, "width": 451, "height": 96 },
  "readingOrder": 14,
  "method": "text-local",
  "confidence": 0.82,
  "notes": "continues from page 8"
}

The point of the JSON profile is not the JSON. It is that a table you are unsure about carries the page and the rectangle to go check.

OCR: pay per page, not per document

OCR is the expensive part of any conversion, in time and in money, and most documents do not need it everywhere. Use it when:

• A page has no extractable text at all, or produces far less than the pages around it.
• Text extracts as garbage characters, which usually means an embedded font with no usable character map.
• A page is a photograph, a signed exhibit, or a diagram whose labels you actually need.
• A table's structure matters more than its text, and the lines are drawn rather than encoded.

Everything else — the ordinary text pages that make up most of a document — should be handled locally, which is also the version that never uploads your file. That split is the whole model behind how this converter works.

Match the output profile to where the Markdown is going

Parse once, then render for the destination. Clean reading Markdown, an Obsidian note, a docs-site page, and retrieval chunks are different products of the same parse.

All five are available on the output profiles section of the converter, and all of them run on the same local parse.

A workflow you can repeat

1. Run the whole document through local extraction first. It is free, it is fast, and it tells you which pages are a problem.
2. Read the flagged pages, not the whole output. Those are where scans, tables, and formulas live.
3. Approve OCR or layout parsing for those pages only.
4. Do the five-minute verification pass above, using page and coordinate provenance to check anything that looks off.
5. Export the profile that matches the destination, and keep the source map if the document matters.

The result is a conversion you can defend: not because a tool claimed 99% accuracy, but because every line points back to the page it came from. Try it on one of the real samples before you trust it with a document that matters.

PDF to Markdown conversion questions