helebest/holo-epub-reader

holo-epub-reader

Parse EPUB files into LLM-friendly Markdown + images with output validation. Zero external dependencies (Python stdlib only).

When to Use

• Extract chapter text from EPUB into clean Markdown
• Get table of contents and heading structure from EPUB metadata
• Extract images alongside text content
• Validate that EPUB output is complete (all referenced images exist)

When NOT to Use

• PDF files — this only handles EPUB (.epub)
• DRM-protected EPUB files — ZIP extraction will fail
• Already-extracted text or Markdown files

Prerequisites

• Python >= 3.10 (no additional packages required, stdlib only)
• EPUB file must be readable
• Output directory must be writable

Quick Start

1) Environment check

bash ./scripts/doctor.sh

2) Parse EPUB

bash ./scripts/parse.sh /path/to/book.epub /path/to/output

3) Validate output

bash ./scripts/validate.sh /path/to/output

CLI Flags

| Flag | Default | Description | |------|---------|-------------| | --no-images | off | Skip extracting image files (still emits image blocks in Markdown) | | --keep-nav | off | Keep navigation/header/footer content instead of stripping | | --max-chunk | 1200 | Maximum characters per text block | | --quiet | off | Suppress manifest JSON summary output |

Output Structure

output-dir/
├── content.md       # Markdown with auto-generated TOC, chapters, headings, images
├── manifest.json    # Metadata: title, creator, block count, image list, timestamps
└── images/          # Extracted images preserving EPUB paths (unless --no-images)
    └── OEBPS/images/
        └── cover.jpg

Note: --no-images skips image file extraction but preserves image references in Markdown (e.g. ![alt](images/...)) for LLM semantic context. If you need portable Markdown without broken image links, do not use this flag.

content.md example:

# Book Title

_Author Name_

---

## Table of Contents
- [Chapter One](#chapter-one)
- [Chapter Two](#chapter-two)

---

## Chapter One

Paragraph text here...

![Alt text](images/OEBPS/images/fig1.jpg)

## Chapter Two

More text...

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Parse or validation error | | 2 | Doctor check failed (Python not found or version too low) |

Edge Cases

• Very large EPUBs: No size limit, but use --max-chunk to control block size
• DRM-protected EPUBs: ZIP extraction fails with exit code 1
• Missing images in EPUB: Reported in manifest.json missing_images array, not a fatal error
• No spine items: Produces valid but empty output (0 blocks)

Environment Configuration

Set EPUB_READER_PYTHON to override Python interpreter discovery:

export EPUB_READER_PYTHON=/usr/bin/python3.12
bash ./scripts/parse.sh book.epub output/

Shell script resolution order: $EPUB_READER_PYTHON > project .venv in CWD > $HOME/.openclaw/.venv/bin/python3 > python3 > python