3.1 KiB
3.1 KiB
categories, tags, created, source, type, aliases
| categories | tags | created | source | type | aliases | |||||
|---|---|---|---|---|---|---|---|---|---|---|
|
|
2026-04-10 | raw/epub-to-markdown-source.md | tool |
|
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
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 [--output ]
- 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
来源
溯源规则：所有数字/百分比/具体结论必须标注
[raw:{文件名}:{行号}]格式。