---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - tool
  - epub-to-markdown
created: 2026-04-10
source: "[[raw/epub-to-markdown-source.md]]"
type: tool
aliases:
  - epub-to-markdown
---

# epub-to-markdown

A skill to extract chapters from EPUB files and convert them into per-chapter Markdown for Obsidian.

## Overview

- Purpose: convert EPUB e-books to per-chapter Markdown with Obsidian frontmatter.
- Inputs/Outputs: EPUB path -> raw/《书名》作者/ 章节 Markdown files.

## How to use

- Trigger phrases: "convert epub", "extract epub", "epub to markdown", "split epub"
- Example:
```
python scripts/extract_epub.py "book.epub" --output raw
```

-## Related Resources
- See the raw source page: [[raw/epub-to-markdown-source.md]]
- Script reference: [[epub-to-markdown/scripts/extract_epub.py|scripts/extract_epub.py]]

## Design & Data Flow

- The process starts by unpacking the EPUB (content.opf for metadata, toc.ncx for chapters, and text/ for HTML content).
- Metadata (title, author, isbn, publisher) are captured and used to construct the per-chapter frontmatter.
- toc.ncx is parsed to map top-level chapters and nested sections; chapters are emitted as separate Markdown files under raw/《书名》作者/.
- HTML content is converted to Markdown via html2text, then cleaned for consistent formatting before writing.

## CLI & API

- Primary entry point: python scripts/extract_epub.py <path-to-epub> [--output <path>]
- Output directory defaults to raw/ and a subdirectory named "《Short Title》Author" is created.
- The tool can be extended to accept options like: --no-cleanup, --split-by, --language, etc.

## Example: Full Run

```
python scripts/extract_epub.py "2020-07《大国大民》.epub" --output raw
```

This will generate one Markdown file per chapter under raw/《大国大民》王志纲/

## Edge Cases & Limitations

- EPUBs without toc.ncx: falls back to spine-based grouping.
- Chapters with multi-part splits: handled by grouping partXXX_split_YYY files.
- Titles containing punctuation: prefixes are sanitized for filesystem safety.
- Non-UTF-8 metadata: may require manual correction.

## Troubleshooting

- If you see missing chapters, verify toc.ncx exists and is well-formed.
- If an EPUB uses an unusual internal structure, inspect the extracted raw/ directory to identify correct text/ subpaths.
- Ensure Python dependencies are installed: bs4, html2text, lxml.

## Validation & Testing

- Validate by running the full end-to-end command on a sample EPUB and inspecting the generated MD files for correctness (frontmatter, title, and body).
- Add unit tests for the HTML-to-Markdown conversion if you diversify input HTML structures.

## Maintenance & Extension

- To add support for more EPUB variants, extend the parser for metadata or adjust the folder layout rules in the script.
- Consider adding a dry-run mode to preview which files would be created without writing to disk.

## References

- raw/epub-to-markdown-source.md
- scripts/extract_epub.py