PDF to Markdown for Developers

I'm writing this from the perspective of someone who builds small web tools with Claude Code and other AI agents. The reason I convert PDFs to Markdown isn't usually documentation generation — it's input shaping. Markdown is the format LLMs read best, and a lot of the source material I want to feed them lives in PDFs.

If you're a developer thinking about adding PDF-to-Markdown to your own workflow, here's what I'd actually do.

The main use case: feeding LLMs

This is where Markdown earns its keep. When I'm building a website that needs to integrate some API — say, a payments provider, a search service, a notification platform — I usually start by grabbing their official docs. About half the time those docs are a PDF (especially with banks and payment processors). The other half they're a docs site, but I want them as one offline artifact.

The naive thing is to paste the PDF directly into Claude. This works badly. Claude can read PDFs, but the file is large in tokens, the structure is opaque, and the model often misses sections. Converting to Markdown first gives me three wins:

• Smaller token count for the same content. PDFs carry a lot of layout overhead.
• Preserved structure. Headings stay headings, and Claude uses the heading hierarchy as a navigation aid when answering questions.
• Editable. I can drop sections I don't need before pasting. The "Authentication" chapter is usually all I want, not the whole 200-page reference.

My loop is: PDF in → PDF2MD → trim by hand → paste into Claude Code as context → ask for the integration code. Total time before code starts being written: about two minutes.

In a build pipeline

If you want to convert PDFs as part of a CI/CD or batch process, the browser tool is the wrong answer. Use a CLI:

• Marker is a Python library and the one I'd reach for first. Install it via pip, then run it on a single PDF or a directory. It does headings, tables, and OCR.
• MinerU is similar. Better for Chinese, slightly heavier setup.
• Pandoc handles the non-PDF cases (DOCX, HTML, EPUB) and you can chain it with one of the above for a unified pipeline.

A pattern I've used: a small repo where docs/.pdf gets watched, and on every push, a GitHub Action runs Marker and commits the resulting docs/.md back. Means the LLM-friendly version is always one commit behind the canonical PDF.

Editor integration

I write in Obsidian for personal notes and VS Code for code. Both treat Markdown as native, so there's no integration step beyond "save the .md file in the right folder."

A few quality-of-life things I've added:

• An Obsidian QuickAdd action that opens PDF2MD with the current PDF. Saves three clicks.
• A VS Code task that runs Marker on the currently open PDF (when I happen to have one open in a viewer extension) and writes a sibling .md.
• For the writing-research workflow specifically, I have a folder per article, and a tiny script that converts every PDF and Word doc in the folder to Markdown so I can grep across them. Without conversion, I can't grep — that's the whole point.

RAG and embeddings

If you're building a RAG pipeline, Markdown is generally the right intermediate format. Most chunkers split on heading boundaries, so preserving heading structure during conversion matters. The converters that do this well are Marker and Nanonets; the converters that flatten everything (text-only extractors) make your chunks worse.

The other thing to watch: tables. Most embedding models don't handle table structure well, and a converter that produces clean pipe-Markdown tables will give you cleaner chunks than one that produces "Column1: value Column2: value" prose. If your corpus is heavy on tables (financial reports, scientific data), test a few converters on a representative document and see which gives you embeddings that retrieve well.

Privacy and self-hosting

For anything that touches client data, contracts, or unpublished work, I won't use a server-side converter. The options that don't upload your file:

• Browser-only, like PDF2MD. Page loads, file processes locally, nothing leaves your machine. Good for ad-hoc.
• Self-hosted CLI, like Marker or MinerU. Good for pipelines.
• Self-hosted server, if you want a long-running internal API. Marker has a server mode. MinerU does too.

What I avoid: any service that requires an upload and doesn't tell you exactly what they do with the file. Even the ones that say "we delete after processing" — I just don't have a way to verify that and I'd rather not have to.

What I'd skip

A few things I've tried and don't bother with anymore:

• Browser extensions that promise PDF→Markdown. Most are wrappers around a server API, and the privacy story is unclear.
• Online "AI-powered" converters for the LLM-feeding use case. I'd rather have a clean deterministic conversion and let Claude handle the intelligence on the other side. Two layers of AI is two layers of opacity.
• Custom parsers I write myself. I've done this. It's a tar pit. Use one of the existing tools.

That's the developer angle. The single biggest piece of leverage from the whole pipeline is "Markdown into Claude Code instead of PDF into Claude," and that's true regardless of which converter you pick.

Last updated: April 6, 2026