redasadki/epub2md

O que epub2md faz?

Convert an EPUB into Markdown, with TOC and spine aware chapter grouping.

When to use this skill

Use this skill when the user:

• Provides an EPUB file (.epub) and asks to convert it to Markdown.
• Asks for the text of an ebook as one Markdown file, or as one Markdown file per chapter.
• Wants to split an EPUB by chapter for downstream processing (indexing, embeddings, translation, review).
• Asks to inspect an EPUB's structure (spine, TOC, chapters).

Do not use this skill for PDFs, Word documents, or web pages. Use format-specific tools instead.

Inputs

• An EPUB file path.
• Optional output directory (default: ./output).
• Optional mode: single, chapters, or both (default: both).
• Optional grouping: toc, spine, or auto (default: auto).

Outputs

Always produced (in the output directory):

• book-extracted/ — raw unzipped EPUB contents.
• book-assets/ — images and media referenced by the book.
• chapters/NN-slug.md — one Markdown file per chapter.
• chapters.json — chapter manifest with title, source files, anchors, output path.
• combined.html — chapters concatenated for inspection.
• book.md — the full book as one Markdown file.
• metadata.json — title, authors, language, identifier, publisher, EPUB version, chapter count.

How to run

The skill ships a runner at scripts/run.sh that finds the epub2md CLI and forwards all arguments. It works whether or not epub2md is installed:

1. If epub2md is on PATH, it is used directly.
2. Otherwise, if the epub2md Python package is importable, python3 -m epub2md is used.
3. Otherwise, the runner falls back to the source tree next to it (scripts/epub2md/), so the skill works out of a fresh clone without any install step.

bash scripts/run.sh path/to/book.epub -o output/ --overwrite

Preferred for repeat use: install the package once.

pip install .
epub2md path/to/book.epub -o output/ --overwrite

For high fidelity conversion, install Pandoc. epub2md uses Pandoc when it is available on PATH and falls back to a pure-Python converter otherwise.

Common recipes

Convert to one Markdown file

bash scripts/run.sh book.epub -o out/ --mode single --overwrite
# reads: out/book.md

Split by chapter using the TOC

bash scripts/run.sh book.epub -o out/ --mode chapters --group-by toc --overwrite
# reads: out/chapters/NN-slug.md and out/chapters.json

Force spine-based grouping

Use when the TOC is missing, malformed, or misleading.

bash scripts/run.sh book.epub -o out/ --group-by spine --overwrite

Use as a Python library

from epub2md import convert

result = convert("book.epub", output_dir="out", mode="both", overwrite=True)
print(result.book_md)
print(len(result.chapters))

Grouping logic

• If a TOC exists, the default auto mode uses it. Each top level TOC entry becomes one chapter. The chapter includes every spine document from the entry's start file up to the next entry's start file. This reassembles chapters that are split across many XHTML files.
• If the TOC is missing, the tool falls back to the spine. Each spine document becomes one chapter.
• Front matter that appears in the spine before the first TOC entry is grouped as one "Front matter" chapter.

Error handling

• Missing container.xml or OPF: the tool exits with a clear message; the EPUB is invalid.
• Malformed XHTML fragments: parsed with lenient mode. When conversion fails for a fragment, the raw HTML is embedded in a fenced block so no content is lost.
• Missing referenced images: warn and keep the original src in the Markdown output.
• Pandoc not installed: the tool silently falls back to markdownify in auto mode.

References

• references/spec.md — full specification, grouping algorithm, and output layout.
• references/troubleshooting.md — practical fixes for common EPUB conversion issues.