pdf2md/README.md

ljutsch – PDF → Markdown → EPUB

Werkzeug, um PDF-Bücher in sauberes Markdown und anschließend in ein EPUB für den PocketBook-Reader umzuwandeln – mit Überschriften, Bildern und echten Absätzen. Funktioniert für digitale PDFs (Textebene vorhanden) ebenso wie für gescannte PDFs (nur Bilder, per OCR) und für Scans, die bereits eine OCR-Ebene haben (z. B. von ocrmypdf).

Entwickelt an Operation Ljutsch (Band 1 und 2), außerdem erprobt an einem deutschen Sachbuch, einem englischen Handbuch, einem Mathematikbuch, einem Bericht mit Fußnoten und einem englischen Scan von 1893 (Ergebnisse siehe Grenzen).

Installation (Ubuntu 24.04)

sudo apt install tesseract-ocr tesseract-ocr-deu pandoc
pip install -r requirements.txt     # pymupdf4llm, pymupdf-layout, pytest

tesseract-ocr wird nur für Scans gebraucht, pandoc nur für --epub.

Verwendung

Ausführliche Schritt-für-Schritt-Anleitung, auch für den Weg „Markdown von Hand bearbeiten, dann EPUB“: BEDIENUNGSANLEITUNG.md.

# digitales oder gescanntes PDF -> Markdown (OCR wird automatisch entschieden)
python3 pdf2md.py buch.pdf buch.md

# zusätzlich Bilder und EPUB (Titel/Autor aus den PDF-Metadaten, Seite 1 als Cover)
python3 pdf2md.py --epub buch.pdf buch.md

# Scan in Deutsch und Englisch, 8 parallele OCR-Prozesse
python3 pdf2md.py --ocr-language deu+eng --jobs 8 scan.pdf scan.md

# englisches Buch; alter Scan mit schlechter OCR-Ebene neu erkennen
python3 pdf2md.py --epub --lang en --ocr-language eng --ocr always scan.pdf scan.md

Option	Bedeutung
--ocr auto (Standard)	Scanseiten per OCR lesen; vorhandene, gerade OCR-Ebenen übernehmen, schiefe neu erkennen; reine Bildseiten in digitalen PDFs (Fotos, Cover) nur nach erfolgreicher Probe-OCR
--ocr always / --ocr never (--no-ocr)	alle Seiten neu erkennen / keine OCR
--ocr-language, --ocr-dpi	Tesseract-Sprache(n) (deu), Auflösung (300)
--jobs N	parallele OCR-Prozesse (Standard 4); reine Textdokumente laufen immer sequenziell
--images	Grafiken in <name>_images/ speichern und verlinken
--image-format jpg|png	Bildformat (Standard jpg; png verlustfrei, aber ca. 3× größer)
--epub, --epub-file PFAD	EPUB 3 mit pandoc erzeugen (schaltet --images ein)
--lang	Sprache im EPUB (de)
--keep-headers, --keep-footers	Kolumnentitel bzw. Seitenzahlen nicht entfernen

Was die Nachbearbeitung macht

• Absätze: Zeilen werden verbunden; eine Absatzgrenze gilt nur nach Satzende (. ! ? …, auch mit « “ » usw. dahinter). Auf Scans werden Absätze am Einzug erkannt.
• Silbentrennung: Geheim-|dienst → Geheimdienst, Militär-|Geheimdienst bleibt mit Bindestrich, Arbeits- und bleibt. Weiche Trennstriche (U+00AD) und ¬ am Zeilenende werden ebenfalls aufgelöst (wach­|senden → wachsenden).
• Überschriften: Ebenen aus den PDF-Lesezeichen (Teile ##, Kapitel ###); Satzreste, die fälschlich als Überschrift erkannt wurden, kommen zurück in den Text.
• Inhaltsverzeichnis: zusammengeklebte Einträge werden getrennt; liegt das Verzeichnis als Tabelle vor, bleibt die Tabelle erhalten.
• OCR-Ebenen in Courier werden nicht als Programmcode (`…`) gesetzt.
• Seitenzahlen, Kolumnentitel, Text in Fotos werden entfernt.

Tests

python3 -m pytest            # ca. 30 s; OCR-/EPUB-Tests werden ohne Tesseract/pandoc übersprungen

Die Test-PDFs (digital, gescannt, mit OCR-Ebene, gemischt, Fotoseite) werden zur Laufzeit synthetisch erzeugt.

Grenzen

• Die Ergebnisqualität hängt von pymupdf4llm/pymupdf-layout ab. Einige Schwächen der Bibliothek gleicht pdf2md.py per Patch aus (Bindestriche und weiche Trennstriche am Zeilenende, Absätze in Scan-Blöcken, OCR-Ebenen in Courier). Eine weitere ist bekannt: Bei Schriften mit Ligaturen (ff, fi) mit übergroßer Glyphenbox kann pymupdf4llm einzelne Zeilen verlieren. Bei den Ljutsch-Bänden tritt das nicht auf (geprüft per Wortabgleich PDF ↔ Markdown).
• OCR-Fehler (z. B. fehlende Leerzeichen) werden nicht korrigiert. Bei alten Scans mit mitgelieferter OCR-Ebene liefert --ocr always meist deutlich besseren Text.
• Mathematische Formeln werden als Bilder übernommen; für Mathebücher ist ein anderes Werkzeug besser geeignet (z. B. Marker, Nougat).
• Was am PDF liegt, bleibt: fehlende Ligaturen ohne Textzuordnung („Offzielle“), gesperrt gesetzte Überschriften („M e i n k l e i nes …“), flache PDF-Gliederungen (alle Kapitel auf einer Ebene).
• Reine Zahlen können als Überschrift erscheinen (Fußnotenzeichen, römische Seitenzahlen). Weitere bekannte Schwächen: TODO.md.
• Bilder werden als JPEG (Qualität 95) gespeichert; EPUB Band 1 ca. 5 MB.

Dateien

• pdf2md.py – aktuelle Version
• tests/ – pytest-Suite