PDF naar Markdown converteren in Python

Waarom Markdown, en waarom dit lastiger is dan het lijkt

LLM's gaan uitzonderlijk goed om met Markdown: koppen markeren sectiegrenzen, pipe-tabellen houden tabelgegevens uitgelijnd, en lijsten blijven lijsten. Voer je een model ruwe uit PDF geëxtraheerde tekst, dan raak je dat allemaal kwijt — en de PDF-binary invoeren is voor de meeste pijplijnen geen optie. Daarom converteert vrijwel elke serieuze RAG-stack documenten naar Markdown vóór chunking en embedding.

Het lastige is dat PDF's geen structuur bevatten — ze bevatten tekens op x/y-coördinaten. Een converter moet reverse-engineeren welke regels koppen zijn (uit de lettergrootte), welke woorden samen een tabel vormen (uit de uitlijning) en wat de leesvolgorde is (uit lay-outanalyse). Libraries verschillen enorm in hoe goed ze dit doen, en daarom is de keuze belangrijk.

Een tweede complicatie: gescande PDF's bevatten helemaal geen tekst, alleen afbeeldingen van pagina's. Slechts een deel van de opties hieronder kan daarmee overweg, via OCR.

Optie 1: PyMuPDF4LLM — snel en licht

PyMuPDF4LLM is een dun laagje bovenop PyMuPDF (fitz), speciaal gebouwd voor LLM-pijplijnen: pip install pymupdf4llm, daarna md = pymupdf4llm.to_markdown("doc.pdf") — één regel, en het is erg snel: de meeste documenten zijn ruim binnen een seconde verwerkt.

Het detecteert koppen op basis van lettergroottes, rendert tabellen als pipe-tabellen en kan pagina-chunks met metadata uitsturen voor directe ingestie in LlamaIndex of LangChain. Voor digitaal geboren PDF's met een rechttoe-rechtaan lay-out — rapporten, documentatie, papers zonder exotische opmaak — is het een uitstekende standaardkeuze.

Beperkingen: geen OCR, dus gescande pagina's komen leeg terug. Complexe meerkolomslay-outs en ingewikkelde tabellen kunnen door elkaar raken, omdat de onderliggende heuristieken snelheid verkiezen boven diepe lay-outanalyse. Licentienoot: PyMuPDF is AGPL — prima voor interne tools, maar overleg met je juridische team voordat je het in een commercieel product verscheept.

Optie 2: Marker — hoogste kwaliteit, GPU vereist

Marker gebruikt een pijplijn van deep-learningmodellen voor lay-outdetectie, leesvolgorde en tabelstructuur, en produceert de meest getrouwe Markdown van alle open-sourceopties — het kan overweg met academische papers in meerdere kolommen, complexe tabellen en zelfs formules.

De prijs is infrastructuur: modelgewichten van meerdere gigabytes, een GPU voor redelijke snelheid (CPU werkt maar is traag — vaak tientallen seconden per document) en een zware dependency-tree die serieuze moeite kost om in productie of serverless omgevingen te deployen.

Kies Marker wanneer outputkwaliteit op lastige documenten de hoogste prioriteit heeft en je de hardware hebt — een academisch corpus bulk-converteren op een GPU-machine is zijn sweet spot. Voor een lichtgewicht service of een serverless functie valt het door het operationele gewicht meestal af.

Optie 3: MarkItDown — Microsofts alles-in-één converter

MarkItDown is Microsofts open-source alles-naar-Markdown-library: pip install markitdown, daarna MarkItDown().convert("doc.pdf").text_content. Zijn kracht is breedte — dezelfde API converteert PDF, DOCX, PPTX, XLSX, HTML en meer, en daarom ging hij viraal voor LLM-datavoorbereiding.

Specifiek voor PDF's is de extractie eenvoudiger dan bij de gespecialiseerde opties: hij leunt op basale tekstextractie, waardoor kopdetectie en tabelgetrouwheid achterblijven bij PyMuPDF4LLM en Marker, en gescande PDF's extra OCR-configuratie nodig hebben.

Kies MarkItDown wanneer je één dependency wilt die veel bestandstypen dekt op gemiddelde kwaliteit — een intern ingestiescript dat "alles wat mensen uploaden" moet accepteren — en niet de best mogelijke PDF-output.

Optie 4: een gehoste API — helemaal geen dependencies

De vierde optie is de conversie niet lokaal draaien: POST de PDF naar een parsing-API en krijg Markdown terug. Met ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — het "text"-veld van de JSON-response is de Markdown.

Deze route heeft OCR voor gescande pagina's ingebouwd, geen modelgewichten of native libraries om te installeren, en werkt identiek in een serverless functie, een container of een notebook. Hij omzeilt bovendien de AGPL-kwestie volledig. De afweging is een netwerk-roundtrip en kosten per document na de gratis laag (300 credits/maand gratis; een PDF kost 3 credits).

Kies de API wanneer je de pijplijn vandaag nog draaiend wilt hebben, wanneer je PDF's scans bevatten, of wanneer je deployt op een plek waar zware dependencies pijn doen — Lambda, Cloud Run, Vercel.

Welke moet je gebruiken?

Digitaal geboren PDF's, eenvoudige tot gemiddelde lay-outs, snelheid telt: PyMuPDF4LLM. De beste verhouding tussen moeite en kwaliteit in pure Python.

Lastige documenten (papers in meerdere kolommen, complexe tabellen) en je hebt een GPU: Marker. Niets open-source verslaat zijn outputkwaliteit.

Veel verschillende bestandstypen via één library, gemiddelde kwaliteit is prima: MarkItDown.

Gescande PDF's in de mix, serverless deployment of geen zin in dependency-beheer: de gehoste API. Eén HTTP-call, OCR inbegrepen, hetzelfde outputschema voor elk document.

Compleet voorbeeld: map met PDF's naar Markdown-bestanden

Welke route je ook kiest, de vorm van de pijplijn is hetzelfde — itereren, converteren, wegschrijven. Hier met de API (verwissel de binnenste call met pymupdf4llm.to_markdown() om het lokaal te draaien):

import httpx; from pathlib import Path — daarna voor elke pdf in Path("pdfs/").glob("*.pdf"): resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

Chunk voor RAG-ingestie de Markdown op koppen in plaats van op vaste tekenaantallen — kopbewuste chunks houden secties intact en retrieven dramatisch beter. Die structurele getrouwheid is precies waarom de conversiestap zorgvuldig doen de moeite waard was.