redasadki/epub2md

epub2md 是做什麼的？

將 EPUB 轉換為 Markdown，具有目錄與 spine 感知的章節分組功能。

何時使用此技能

當使用者有以下需求時，可使用此技能：

• 提供一個 EPUB 檔案（.epub）並要求將其轉換為 Markdown。
• 要求將電子書的文字輸出為一個 Markdown 檔案，或每個章節一個 Markdown 檔案。
• 希望將 EPUB 按章節分割，以便進行後續處理（索引、嵌入、翻譯、審閱）。
• 要求檢查 EPUB 的結構（spine、目錄、章節）。

請勿將此技能用於 PDF、Word 文件或網頁。請改用其他專用的格式工具。

輸入

• 一個 EPUB 檔案路徑。
• 可選的輸出目錄（預設：./output）。
• 可選的模式：single、chapters 或 both（預設：both）。
• 可選的分組方式：toc、spine 或 auto（預設：auto）。

輸出

始終在輸出目錄中產生以下內容：

• book-extracted/ ── 原始解壓縮後的 EPUB 內容。
• book-assets/ ── 書中引用的圖片與多媒體檔案。
• chapters/NN-slug.md ── 每個章節一個 Markdown 檔案。
• chapters.json ── 章節清單，包含標題、來源檔案、錨點、輸出路徑。
• combined.html ── 所有章節串聯後的 HTML，供檢查用。
• book.md ── 整本書合併為一個 Markdown 檔案。
• metadata.json ── 標題、作者、語言、識別碼、出版社、EPUB 版本、章節數量。

如何執行

此技能在 scripts/run.sh 提供一個執行器，它會自動找到 epub2md 指令並轉發所有參數。無論 epub2md 是否已安裝，它都能運作：

1. 如果 epub2md 在 PATH 中，則直接使用。
2. 否則，如果 epub2md Python 套件可匯入，則使用 python3 -m epub2md。
3. 否則，執行器會回退到其旁邊的原始碼樹（scripts/epub2md/），因此從全新克隆的儲存庫中無需任何安裝步驟即可運作。

bash scripts/run.sh path/to/book.epub -o output/ --overwrite

建議重複使用時，先安裝套件一次。

pip install .
epub2md path/to/book.epub -o output/ --overwrite

為獲得高保真轉換結果，請安裝 Pandoc。epub2md 在 Pandoc 存在於 PATH 時會自動使用它，否則會回退到純 Python 轉換器。

常見使用情境

轉換為一個 Markdown 檔案

bash scripts/run.sh book.epub -o out/ --mode single --overwrite
# 讀取: out/book.md

使用目錄按章節分割

bash scripts/run.sh book.epub -o out/ --mode chapters --group-by toc --overwrite
# 讀取: out/chapters/NN-slug.md 和 out/chapters.json

強制使用 spine 分組

當目錄缺失、格式錯誤或誤導時使用。

bash scripts/run.sh book.epub -o out/ --group-by spine --overwrite

作為 Python 函式庫使用

from epub2md import convert

result = convert("book.epub", output_dir="out", mode="both", overwrite=True)
print(result.book_md)
print(len(result.chapters))

分組邏輯

• 如果存在目錄，預設的 auto 模式會使用它。每個頂層目錄項目會成為一個章節。該章節會包含從該項目的起始檔案到下一個項目的起始檔案之間的所有 spine 文件。這會將分散在多個 XHTML 檔案中的章節重新組合起來。
• 如果目錄缺失，工具會回退到使用 spine。每個 spine 文件會成為一個章節。
• 在 spine 中出現在第一個目錄項目之前的 front matter 會被分組為一個「Front matter」章節。

錯誤處理

• 遺失 container.xml 或 OPF：工具會退出並顯示清楚的訊息；該 EPUB 格式無效。
• 格式錯誤的 XHTML 片段：會以寬鬆模式解析。當某個片段的轉換失敗時，原始 HTML 會被嵌入到一個圍欄程式碼區塊中，因此不會遺失任何內容。
• 遺失引用的圖片：發出警告，並在 Markdown 輸出中保留原始的 src 屬性。
• Pandoc 未安裝：工具會以自動模式靜默地回退到使用 markdownify。

參考資料

• references/spec.md ── 完整規格說明、分組演算法及輸出佈局。
• references/troubleshooting.md ── 針對常見 EPUB 轉換問題的實用解決方案。