epub2md

Was macht epub2md?

Konvertiert ein EPUB in Markdown, mit TOC- und Spine-basierter Kapitelgruppierung.

Wann dieses Skill verwendet werden sollte

Verwenden Sie dieses Skill, wenn der Benutzer:

• Eine EPUB-Datei (.epub) bereitstellt und nach einer Konvertierung zu Markdown fragt.
• Den Text eines E-Books als eine einzige Markdown-Datei oder als eine Markdown-Datei pro Kapitel haben möchte.
• Ein EPUB nach Kapiteln für die Weiterverarbeitung (Indizierung, Embeddings, Übersetzung, Review) aufteilen möchte.
• Die Struktur eines EPUBs (Spine, TOC, Kapitel) untersuchen möchte.

Verwenden Sie dieses Skill nicht für PDFs, Word-Dokumente oder Webseiten. Verwenden Sie stattdessen formatspezifische Werkzeuge.

Eingaben

• Ein EPUB-Dateipfad.
• Optionales Ausgabeverzeichnis (Standard: ./output).
• Optionaler Modus: single, chapters oder both (Standard: both).
• Optionale Gruppierung: toc, spine oder auto (Standard: auto).

Ausgaben

Immer erzeugt (im Ausgabeverzeichnis):

• book-extracted/ — entpackte Rohe-EPUB-Inhalte.
• book-assets/ — Bilder und Medien, auf die das Buch verweist.
• chapters/NN-slug.md — eine Markdown-Datei pro Kapitel.
• chapters.json — Kapitelmanifest mit Titel, Quelldateien, Ankern und Ausgabepfad.
• combined.html — Kapitel verkettet zur Überprüfung.
• book.md — das gesamte Buch als eine Markdown-Datei.
• metadata.json — Titel, Autoren, Sprache, Identifikator, Verlag, EPUB-Version, Kapitelanzahl.

Ausführung

Das Skill enthält einen Runner unter scripts/run.sh, der die epub2md-CLI findet und alle Argumente weitergibt. Es funktioniert unabhängig davon, ob epub2md installiert ist oder nicht:

1. Wenn epub2md im Pfad (PATH) ist, wird es direkt verwendet.
2. Andernfalls, wenn das Python-Paket epub2md importierbar ist, wird python3 -m epub2md verwendet.
3. Andernfalls greift der Runner auf das Quellverzeichnis in seiner Nähe zurück (scripts/epub2md/), sodass das Skill aus einem frischen Klon ohne Installationsschritt funktioniert.

bash scripts/run.sh pfad/zum/buch.epub -o ausgabe/ --overwrite

Für die wiederholte Nutzung empfohlen: Installieren Sie das Paket einmal.

pip install .
epub2md pfad/zum/buch.epub -o ausgabe/ --overwrite

Für eine hohe Wiedergabetreue installieren Sie Pandoc. epub2md verwendet Pandoc, wenn es sich im Pfad befindet, und greift andernfalls auf einen reinen Python-Konverter zurück.

Häufige Rezepte

In eine einzelne Markdown-Datei konvertieren

bash scripts/run.sh buch.epub -o aus/ --mode single --overwrite
# liest: aus/book.md

Nach Kapitel mit dem Inhaltsverzeichnis aufteilen

bash scripts/run.sh buch.epub -o aus/ --mode chapters --group-by toc --overwrite
# liest: aus/chapters/NN-slug.md und aus/chapters.json

Spine-basierte Gruppierung erzwingen

Verwenden Sie dies, wenn das Inhaltsverzeichnis fehlt, fehlerhaft oder irreführend ist.

bash scripts/run.sh buch.epub -o aus/ --group-by spine --overwrite

Als Python-Bibliothek verwenden

from epub2md import convert

ergebnis = convert("buch.epub", output_dir="aus", mode="both", overwrite=True)
print(ergebnis.book_md)
print(len(ergebnis.chapters))

Gruppierungslogik

• Wenn ein Inhaltsverzeichnis (TOC) existiert, verwendet der Standardmodus auto dieses. Jeder Eintrag der obersten Ebene des TOC wird zu einem Kapitel. Das Kapitel enthält jedes Spine-Dokument von der Startdatei des Eintrags bis zur Startdatei des nächsten Eintrags. Dadurch werden Kapitel, die über mehrere XHTML-Dateien verteilt sind, wieder zusammengesetzt.
• Wenn das Inhaltsverzeichnis fehlt, fällt das Tool auf die Spine-Reihenfolge zurück. Jedes Spine-Dokument wird zu einem Kapitel.
• Frontmatter, das im Spine vor dem ersten TOC-Eintrag erscheint, wird als ein einziges „Front matter“-Kapitel gruppiert.

Fehlerbehandlung

• Fehlende container.xml oder OPF: Das Tool beendet sich mit einer klaren Meldung; das EPUB ist ungültig.
• Fehlerhafte XHTML-Fragmente: werden mit einem nachsichtigen Modus geparst. Wenn die Konvertierung eines Fragments fehlschlägt, wird das rohe HTML in einem Codeblock eingebettet, sodass kein Inhalt verloren geht.
• Fehlende referenzierte Bilder: Warnung ausgeben und das ursprüngliche src-Attribut im Markdown-Ausgabe beibehalten.
• Pandoc nicht installiert: Das Tool fällt im Auto-Modus stillschweigend auf markdownify zurück.

Referenzen

• references/spec.md — vollständige Spezifikation, Gruppierungsalgorithmus und Ausgabelayout.
• references/troubleshooting.md — praktische Lösungen für häufige EPUB-Konvertierungsprobleme.