How I Convert PDFs to Markdown (and What to Watch For)

This is the workflow I actually use, written down so I can point people at it instead of explaining it in DMs.

I'll cover the case I do most often (a normal text PDF, fast path), then the edge cases that come up: scanned PDFs, multi-column layouts, tables that come out scrambled, and a few cleanup tricks that have saved me time.

The fast path

Ninety percent of my PDFs are "normal" — someone typed them in Word or LaTeX and exported, and the text is selectable when you open the file. For these:

1. Open PDF2MD in a browser tab.
2. Drag the file (or twenty files) onto the page.
3. Wait. A 50-page paper takes maybe 4 seconds; a 300-page report can take a minute.
4. Either copy the result or hit "Download all as ZIP" if I did a batch.

That's it. I do this several times a day for API docs going into Claude Code, and for research material going into Obsidian.

The reason it's this fast is that everything runs in your browser using PDF.js. There's no upload, no server queue, no waiting for someone's API to wake up. The flip side is that very large jobs will eat your laptop's CPU for a moment — if I'm doing a 50-file batch I'll start it and switch tabs.

When the fast path fails: scanned PDFs

The single most common "why is the output empty?" cause is a scanned PDF. If you open the PDF and try to select a sentence with your mouse, and you can't, then there's no text in the file — it's an image. PDF2MD doesn't do OCR, so it'll produce an empty Markdown file or just whitespace.

Two ways out:

• OCR first, convert second. I use Marker (which has OCR built in) for these, or I open the PDF in Preview on Mac and re-save with OCR applied (Tools → "Recognise Text"). Then PDF2MD works on it.
• Pay a service for the rare hard case. If it's one weird scanned document and I don't want to install anything, Nanonets or Adobe will OCR and convert. I avoid this for anything sensitive.

How to tell at a glance: if you can't drag-select a sentence in the PDF viewer, it's a scan.

Multi-column layouts

Academic papers and most design-magazine layouts use two or three columns. PDF text is positioned by absolute coordinates, which means a naive extractor will read across columns: "First sentence of left column, first sentence of right column, second sentence of left column…" — gibberish.

PDF2MD tries to detect column breaks and read column-wise. It mostly works, but if you're getting jumbled text out of a multi-column PDF, that's why. Two workarounds I use:

• Convert page by page rather than the whole document, and stitch together. Sometimes the column detector trips on one page and not others.
• Fall back to Marker for the document. Its layout model handles columns better than mine.

Tables come out wrong

This is probably the single most common complaint I get. The reason is that PDFs don't store tables as tables — they store rows of text positioned in columns, with no metadata that says "this is a cell". Every converter is guessing.

My personal fix workflow:

1. Convert and look at the table. If it's structurally right but the alignment is off, leave it; Markdown renderers don't care about whitespace alignment in tables.
2. If cells got merged across rows, find the original PDF, and check whether the cell content wraps onto two lines. Wrapping is what trips most extractors. Often the easiest fix is to retype that one row by hand.
3. If the whole table is gone, copy-paste the table region from the PDF directly into a Markdown editor that supports table-from-paste (Obsidian + a plugin, or Typora). Sometimes the clipboard preserves enough structure.

I've stopped expecting perfect table conversion from any tool. It's the part of PDF parsing that's still genuinely unsolved.

My cleanup pass

Whatever tool I use, I do a 60-second cleanup before the file is "done":

• Search and replace runs of three or more blank lines with two, to collapse spacing weirdness.
• Look at the heading hierarchy. Sometimes an H1 in the source becomes an H3 in the output, or vice versa. Fix the levels so the doc renders right.
• Strip page numbers. PDFs often have "Page 12 of 47" running headers that the converter dutifully includes. I usually grep them out.
• Check for ligatures. Some PDFs encode "fi" and "fl" as single Unicode glyphs, and depending on the converter you'll either see those characters in your output or you'll see "fi"/"fl" missing entirely. PDF2MD normalises these, but if you're using something else, it's worth grepping.

Specific use cases

Going into Claude Code or another LLM. Markdown is the right format. Claude reads structure better in Markdown than in plain text or HTML. I paste API docs into chat after PDF2MD-ing them, and the difference in code generation quality is real. One tip: if the PDF has a giant table of contents at the start, delete it before pasting. It eats tokens and adds nothing.

Note-taking in Obsidian / Logseq. Markdown is native. The thing to watch is wikilinks: PDF2MD outputs standard Markdown links, so if you want double-bracket wikilink style you'll do a quick find-replace.

GitHub READMEs and wikis. Markdown is native, but GitHub-flavoured Markdown is slightly different. Tables are fine. Code blocks are fine. The one thing that breaks: math. If your PDF has equations and you need them to render on GitHub, you'll need a separate pass with something like KaTeX.

Pasting into Notion. Notion accepts Markdown on paste, but it does some opinionated reformatting. Headings are preserved, tables are preserved, but link formatting can get weird. Usually fine, but I always glance at the imported version.

When to give up on the converter

Sometimes the source PDF is just bad. Auto-generated forms, old scanned books, slide decks exported with weird text positioning. After a year of this I've learned to recognise the giveaway smells: more than two converters in a row produce different-but-equally-broken output. When that happens I either retype the part I need (often it's a page or two), or I find the original source — most papers are also on arXiv as LaTeX, most government reports have an HTML version, most product docs have a docs site. The PDF is rarely the only form.

That's the workflow. If you find a PDF that breaks PDF2MD in an interesting way, mail it to [email protected] — I collect them.

Last updated: March 19, 2026