epub2md/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung epub2md

Diese Anleitung zeigt Schritt für Schritt, wie du ein E-Book im EPUB-Format in Markdown umwandelst und was du mit dem Ergebnis anfangen kannst. Technische Details stehen in der README.md.

---

1. Was macht das Programm?

epub2md nimmt ein DRM-freies E-Book (Dateiendung .epub) und erzeugt daraus:

• einen Ordner mit je einer Markdown-Datei pro Kapitel, allen Bildern, einem Inhaltsverzeichnis und einem Prüfbericht (epub2md.py)
• auf Wunsch zusätzlich eine einzige Markdown-Datei mit dem ganzen Buch (epub2md_merge.py)

Markdown ist reiner Text mit einfachen Formatierungszeichen. Du kannst ihn in jedem Editor lesen, in Obsidian ablegen, mit Git versionieren, mit Pandoc in HTML/PDF/Word umwandeln oder an ein lokales Sprachmodell (RAG) übergeben.

Was das Programm nicht kann:

• Kopiergeschützte E-Books (DRM, z. B. aus manchen Online-Shops) öffnen. Sie werden mit einer Meldung abgelehnt.
• Gescannte Bücher in Text verwandeln (keine Texterkennung/OCR).
• Formeln, die im E-Book nur als Bild vorliegen, in echten Formeltext umwandeln. Sie bleiben Bilder.

---

2. Einmalige Einrichtung

Voraussetzung ist Python 3.12 (unter Ubuntu 24.04 vorinstalliert). Im Projektordner:

sudo apt install python3-venv       # nur falls noch nicht vorhanden
cd ~/Python_Programs/epub2md
python3 -m venv .venv               # eigene Python-Umgebung anlegen (einmalig)
source .venv/bin/activate           # Umgebung aktivieren (in jedem neuen Terminal)
pip install -r requirements.txt     # benötigte Bibliothek installieren (einmalig)

Funktioniert die Einrichtung? Dieser Befehl muss eine Versionsnummer ausgeben:

python3 epub2md.py --version

Tipp: Ist die Bibliothek lxml systemweit schon installiert, kannst du die virtuelle Umgebung auch weglassen.

---

3. Ein Buch umwandeln – der Normalfall

python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch

• Erster Wert: die EPUB-Datei.
• Zweiter Wert: der Zielordner. Er darf noch nicht existieren oder muss leer sein.

Am Ende erscheint eine Zusammenfassung, etwa so:

epub2md: 25 Kapitel, 87 Mediendateien, 747 Codeblöcke, 0 Formeln, 27 Anmerkungen, 0 Warnungen, 0 Fehler
Ausgabe: output/meinbuch

Öffne danach output/meinbuch/README.md. Dort findest du Titel, Autor, ein klickbares Inhaltsverzeichnis und eine Statistik.

Vorher nur nachsehen, ohne etwas zu schreiben

python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --dry-run

Zeigt, welche Kapiteldateien entstehen würden. Es wird nichts gespeichert.

Mehr sehen, was gerade passiert

python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --verbose

---

4. Was liegt danach im Zielordner?

output/meinbuch/
├── README.md                 ← hier anfangen: Inhaltsverzeichnis, Metadaten, Statistik
├── chapters/                 ← das Buch, ein Kapitel pro Datei
│   ├── 001-cover.md
│   ├── 002-vorwort.md
│   └── 003-1-einleitung.md …
├── media/images/             ← alle Bilder (jedes nur einmal)
├── metadata.yaml             ← Titel, Autor, Verlag, ISBN … (nur, was im E-Book steht)
├── manifest.json             ← Kapitelliste für Programme (z. B. RAG-Import)
├── conversion-report.json    ← ausführlicher Prüfbericht für Programme
└── diagnostics/
    ├── warnings.md           ← Warnungen in Klartext – bei Problemen hier nachsehen
    └── unsupported-elements.md

Jede Kapiteldatei beginnt mit einem kleinen Datenkopf zwischen zwei ----Zeilen (Buchtitel, Kapitelnummer, Herkunft). Die meisten Markdown-Programme blenden ihn aus oder zeigen ihn als Eigenschaften an, z. B. Obsidian. Willst du ihn nicht haben, wandle mit --no-frontmatter um.

---

5. Das ganze Buch in einer Datei

python3 epub2md_merge.py output/meinbuch

Ergebnis: output/meinbuch/meinbuch.md. Die Datei heißt wie das Original-E-Book, nur mit .md. Bilder und Querverweise funktionieren darin weiter.

Nützliche Varianten:

# mit Inhaltsverzeichnis am Anfang
python3 epub2md_merge.py output/meinbuch --toc

# an einen anderen Ort schreiben (Bildpfade werden automatisch angepasst)
python3 epub2md_merge.py output/meinbuch -o ~/Dokumente/meinbuch.md

# eine schon vorhandene Gesamtdatei überschreiben
python3 epub2md_merge.py output/meinbuch --force

Wichtig: Verschiebst du die Gesamtdatei später von Hand, findet sie ihre Bilder nicht mehr. Nutze dafür -o, dann stimmen die Pfade.

---

6. Rezepte für typische Bücher

Roman (Teile und Kapitel)

Viele Romane gliedern sich in „Teil 1, Teil 2 …“ mit Kapiteln darin. Standardmäßig entsteht eine Datei pro Teil. Das können sehr große Dateien werden. Das Programm warnt dann mit chapter-large und empfiehlt die passende Einstellung. Eine Datei pro Kapitel bekommst du so:

python3 epub2md.py roman.epub output/roman --chapter-level 2

Programmierbuch

python3 epub2md.py python-buch.epub output/python-buch

Programmcode bleibt zeichengenau erhalten, inklusive Einrückung. Die Programmiersprache wird nur eingetragen, wenn sie eindeutig erkennbar ist. Ist das ganze Buch in einer Sprache geschrieben, kannst du sie für alle übrigen Codeblöcke vorgeben:

python3 epub2md.py python-buch.epub output/python-buch --code-language python

Das hilft Editoren beim Einfärben des Codes. Nachteil: Auch Programmausgaben und Shell-Befehle im Buch werden dann als Python markiert.

Mathematikbuch

python3 epub2md.py mathe.epub output/mathe

Formeln, die im E-Book als echte Formeln (MathML oder TeX) vorliegen, werden zu TeX: $…$ im Text, $$…$$ als eigene Zeile. Formeln, die nur als Bild vorliegen, bleiben Bilder und erscheinen in diagnostics/warnings.md.

Gewünschte Formeldarstellung	Option
TeX mit $ (GitHub, Obsidian, Pandoc)	Standard (--math auto)
TeX mit \(…\) und \[…\]	--math tex
Formeln als MathML (für Browser/HTML)	--math mathml
Formeln möglichst als Bilder	--math image

Buch mit vielen Fußnoten

Standardmäßig stehen die Fußnoten am Ende des jeweiligen Kapitels. Alternativen:

Wunsch	Option
Alle Anmerkungen gesammelt in einer eigenen Datei am Buchende	--footnotes end-of-book
Anmerkung direkt in Klammern im Text	--footnotes inline
Fußnoten an ihrer Originalstelle mit Links lassen	--footnotes keep-links

---

7. Weiterverarbeiten

In Obsidian lesen

Kopiere den ganzen Ausgabeordner, z. B. output/meinbuch, in deinen Obsidian-Tresor. Die Kapitel erscheinen als einzelne Notizen, Bilder und Links auf andere Kapitel funktionieren. Der Datenkopf wird als Eigenschaften angezeigt. Sprünge an eine bestimmte Stelle innerhalb eines Kapitels (HTML-Anker wie <a id="…">) unterstützt Obsidian nur eingeschränkt. Solche Links öffnen dann einfach das Kapitel.

Mit Pandoc in HTML, PDF oder EPUB umwandeln

Am einfachsten über die Gesamtdatei. Wechsle dazu in den Ausgabeordner, damit die Bildpfade stimmen:

python3 epub2md_merge.py output/meinbuch
cd output/meinbuch
pandoc meinbuch.md --toc -s -o meinbuch.html              # Webseite
pandoc meinbuch.md --toc -o meinbuch.docx                 # Word
pandoc meinbuch.md --pdf-engine=xelatex -o meinbuch.pdf   # PDF (LaTeX nötig)

Bei Büchern mit Formeln für HTML zusätzlich --mathml angeben, sonst bleiben Matrizen als TeX-Text stehen.

Für ein lokales Sprachmodell (RAG)

• Die einzelnen Kapiteldateien eignen sich als Abschnitte. Die Metadaten im Datenkopf (Buch, Kapitel, Herkunft) helfen beim Zuordnen von Fundstellen.
• manifest.json listet alle Kapitel mit Titel, Datei, Wortanzahl und Ankern.
• Achte auf die Warnung chapter-large: Sehr große Kapiteldateien lassen sich schlecht zerlegen. Dann mit höherem --chapter-level neu umwandeln.

---

8. Ein Buch erneut umwandeln

Ist der Zielordner schon vorhanden, bricht das Programm zum Schutz deiner Daten ab:

epub2md: Fehler: Ausgabeverzeichnis existiert bereits und ist nicht leer: output/meinbuch

Zum Ersetzen einer früheren epub2md-Ausgabe:

python3 epub2md.py Beispiele/meinbuch.epub output/meinbuch --force

--force löscht nur Ordner, die erkennbar von epub2md stammen. Ordner mit anderen Inhalten, dein Home-Verzeichnis oder den aktuellen Arbeitsordner rührt es nicht an.

Achtung: --force ersetzt den ganzen Ordner, also auch eine dort erzeugte Gesamtdatei und alles, was du selbst hineingelegt hast. Eigene Notizen also nicht im Ausgabeordner speichern.

---

9. Warnungen verstehen

Warnungen bedeuten: Die Umwandlung hat funktioniert, aber etwas verdient einen Blick. Alle Warnungen stehen gesammelt in diagnostics/warnings.md.

Meldung (Code)	Bedeutung	Was tun?
chapter-large	Eine Kapiteldatei ist sehr groß (> 30 000 Wörter) und hat Unterkapitel	Mit dem empfohlenen --chapter-level neu umwandeln
formula-image, formula-svg	Formel liegt im E-Book nur als Bild vor	Nichts. Das Bild bleibt erhalten, als Text gibt es diese Formel nicht
mathml-kept	Formel war zu komplex für eine sichere TeX-Umwandlung	Nichts. Sie bleibt als MathML erhalten, HTML-fähige Programme und Browser zeigen sie an
table-html	Tabelle mit verbundenen Zellen o. Ä.	Nichts. Sie bleibt als HTML-Tabelle erhalten, das zeigen die meisten Programme an
unresolved-link	Ein Querverweis im E-Book zeigt ins Leere	Nichts. Der Linktext bleibt stehen, nur ohne Link
anchor-missing	Sprungziel im Kapitel nicht gefunden	Der Link führt zum Kapitelanfang
image-missing, media-missing	Bild/Medium fehlt im E-Book selbst	Fehler der Vorlage, Platzhaltertext eingefügt
noteref-unresolved	Fußnotenzeichen ohne zugehörige Fußnote	Fehler der Vorlage
note-unreferenced	Fußnote, auf die nichts verweist	Bleibt an ihrer Stelle im Text
decode-error	Zeichen im E-Book waren beschädigt	Betroffene Zeichen erscheinen als <EFBFBD>
no-toc	E-Book ohne Inhaltsverzeichnis	Kapiteltitel werden aus dem Inhalt abgeleitet
broken-output-link	Interne Prüfung fand einen kaputten Link in der Ausgabe	Bitte melden, das sollte nicht vorkommen

Fehler, nach denen trotzdem weitergearbeitet wurde, etwa eine fehlende Kapiteldatei im E-Book, stehen ebenfalls dort. Mit --strict bricht das Programm bei solchen kritischen Fehlern stattdessen ab, ohne eine Ausgabe zu schreiben.

---

10. Fehlermeldungen und Lösungen

Meldung (Auszug)	Ursache	Lösung
Eingabedatei nicht gefunden	Pfad zur EPUB-Datei falsch	Pfad prüfen, ggf. in Anführungszeichen setzen (Leerzeichen!)
Ausgabeverzeichnis existiert bereits	Zielordner ist nicht leer	Anderen Zielordner wählen oder --force (siehe Kapitel 8)
--force verweigert	Zielordner stammt nicht von epub2md	Ordner prüfen und selbst leeren oder anderen Ordner wählen
Ausgabeverzeichnis nicht beschreibbar	Keine Schreibrechte	Ordner mit Schreibrechten wählen
Keine gültige ZIP/EPUB-Datei	Datei ist beschädigt oder kein EPUB	Datei neu herunterladen
container.xml fehlt	Beschädigtes oder unvollständiges EPUB	Datei neu herunterladen; ggf. mit Calibre reparieren
verschlüsselt/DRM-geschützt	Kopiergeschütztes E-Book	Wird nicht unterstützt
ZIP-Eintrag zu groß	Ungewöhnlich großer, verdächtiger Inhalt	Schutzfunktion, Datei nicht verwenden
Die Spine enthält keine lesbaren XHTML-Dokumente	E-Book hat keinen lesbaren Text	Datei prüfen
invalid choice / Fehler: argument …	Option falsch geschrieben	python3 epub2md.py --help ansehen

Rückgabecodes für Skripte:

Code	Bedeutung
0	Erfolg, ggf. mit Warnungen
1	Bedienfehler: Optionen, Eingabedatei, Zielordner
2	E-Book-Datei beschädigt, kopiergeschützt oder unsicher
3	Inhalt des E-Books nicht verarbeitbar
4	Unerwarteter Programmfehler. Mit --verbose wiederholen und die Meldung notieren

---

11. Häufige Fragen

Werden meine E-Books irgendwohin hochgeladen? Nein. Das Programm arbeitet vollständig offline und greift nicht aufs Netz zu.

Wird das Original-E-Book verändert? Nein, es wird nur gelesen. Mit --copy-original wird zusätzlich eine Kopie in den Ausgabeordner gelegt.

Warum heißen manche Kapiteldateien seltsam (z. B. cinnertitle)? Manche E-Book-Seiten (Titelseite, Impressum) haben weder Überschrift noch Titel. Dann wird der interne Dateiname verwendet.

Warum steht in einem Codebeispiel ein ↪ oder ist es falsch eingerückt? So steht es im E-Book selbst (Umbruchzeichen bzw. Satzfehler des Verlags). Der Code wird bewusst zeichengetreu übernommen.

Können Dateinamen Umlaute enthalten? Standardmäßig werden Umlaute umschrieben (ä → ae). Mit --slug-language none bleiben sie erhalten, mit --slug-language en wird ä zu a.

Kann ich die Bilder anders ablegen lassen? --images flat legt alle Medien direkt in media/. --images original-path behält die Ordnerstruktur des E-Books bei. Mit --no-extract-media werden gar keine Bilder gespeichert.

Woher weiß ich, ob alles geklappt hat? Steht in der Zusammenfassung 0 Fehler, ist die Umwandlung durchgelaufen. Warnungen erklärt Kapitel 9. Das Programm prüft am Ende selbst alle Links und Bildverweise der Ausgabe.

---

12. Alle Optionen auf einen Blick

python3 epub2md.py --help
python3 epub2md_merge.py --help

Option	Kurz erklärt
--dry-run	nur anzeigen, nichts schreiben
--verbose	ausführliche Ausgabe
--force	frühere Ausgabe ersetzen
--chapter-level N	ab welcher Überschriftenebene eine neue Datei beginnt (Standard 1)
--code-language SPRACHE	Sprache für Codeblöcke ohne erkannte Sprache
--math auto/tex/mathml/image	Formeldarstellung
--footnotes end-of-chapter/end-of-book/inline/keep-links	Fußnoten-Platzierung
--format gfm/commonmark	Markdown-Variante; commonmark für sehr strikte Programme
--images relative/flat/original-path	Ablage der Bilder
--no-extract-media	keine Bilder speichern
--copy-original	Original-EPUB mit in den Ordner legen
--no-frontmatter	ohne Datenkopf in den Kapiteln
--no-toc	ohne README/Inhaltsverzeichnis
--slug-language de/en/none	Umgang mit Umlauten in Dateinamen
--keep-html	Unbekanntes als HTML erhalten statt nur als Text
--strict	bei kritischen Fehlern im E-Book abbrechen
--report DATEI.json	Prüfbericht zusätzlich an anderer Stelle speichern

Merge-Programm: -o DATEI.md (Zielort), --toc (Inhaltsverzeichnis), --no-frontmatter (ohne Buch-Kopf), --force (überschreiben).