89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
---
|
|
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
|
|
|
|
## 来源
|
|
|
|
> **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。
|
|
|
|
- [[raw/epub-to-markdown-source.md]] |