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.

A mature production workflow should route page by page rather than send 200 pages through a model because four are scanned. The current converter switches the whole PDF to Moondream only when its inspected pages are image-only; mixed PDFs follow the Cloudflare text path and should be checked for blank exhibits.

One shortcut is worth checking before any of this: if the PDF was exported from Word and you can still get the original, convert that instead. The .docx keeps the heading styles, list numbering, and table cells that a PDF forces you to infer — the Word to Markdown converter reads them directly and reports what it had to drop.

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.

Verification only works when the converter distinguishes evidence from guesses. This implementation keeps the method and Markdown offsets, uses page markers when Cloudflare returns them, and keeps Moondream confidence for OCR blocks. Bounding boxes remain unavailable unless a provider actually returns coordinates.

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": null,
  "readingOrder": 14,
  "method": "cloudflare-markdown",
  "confidence": null,
  "notes": "not supplied by Cloudflare toMarkdown"
}

The point of the JSON profile is not the JSON. It is that every available source field remains explicit: a page when attributed, null when coordinates or confidence were not returned, and stable Markdown offsets for downstream checks.

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.

Ordinary text PDFs use Cloudflare's document converter after local page analysis. They avoid vision OCR, but the PDF is still uploaded. A fully scanned PDF is rendered in the browser and sent to Moondream 3.1, as explained in how this converter works and the current pricing status.

A page that only exists as a photo — a whiteboard, a notebook page, a printed handout — does not need to be wrapped into a PDF first. The image to Markdown camera takes up to three photos directly and returns the same block-structured Markdown, so handwritten and photographed sources join this workflow without a detour.

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 are generated from the same routed conversion result.

A workflow you can repeat

1. Let the browser inspect the document first. This creates the preview and determines whether the PDF has a usable text layer.
2. Send a text PDF through Cloudflare document conversion, or let a fully scanned PDF be rendered and routed to Moondream 3.1 OCR.
3. Read the flagged pages first. Scans, tables, and formulas are where manual verification matters most.
4. Do the five-minute verification pass above, using page provenance and the original preview 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 easier to audit: not because a tool claimed 99% accuracy, but because page attribution is retained whenever the provider returns it and missing evidence is left blank. Try one of the real samples before you trust it with a document that matters.

PDF to Markdown conversion questions