Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,83 @@
+---
+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