redasadki/epub2md

epub2md は何をしますか？

EPUBをMarkdownに変換します。目次（TOC）とスパインを認識したチャプターグループ化機能を備えています。

このスキルを使用するタイミング

以下のような場合にこのスキルを使用します。

• ユーザーがEPUBファイル（.epub）を提供し、Markdownへの変換を依頼した場合。
• 電子書籍のテキストを1つのMarkdownファイル、またはチャプターごとに1つのMarkdownファイルとして要求された場合。
• 下流の処理（インデックス作成、埋め込みベクトル化、翻訳、レビュー）のために、EPUBをチャプターごとに分割したい場合。
• EPUBの構造（スパイン、目次、チャプター）を調査するように依頼された場合。

PDFやWord文書、Webページには使用しないでください。それらのフォーマット専用のツールを使用してください。

入力

• EPUBファイルのパス。
• オプションの出力ディレクトリ（デフォルト: ./output）。
• オプションのモード: single、chapters、both（デフォルト: both）。
• オプションのグループ化方法: toc、spine、auto（デフォルト: auto）。

出力

常に出力ディレクトリに以下を生成します。

• book-extracted/ — 生の解凍済みEPUBコンテンツ。
• book-assets/ — 書籍で参照されている画像やメディア。
• chapters/NN-slug.md — チャプターごとに1つのMarkdownファイル。
• chapters.json — タイトル、ソースファイル、アンカー、出力パスを含むチャプター一覧。
• combined.html — 確認用に連結された全チャプター。
• book.md — 書籍全体を1つのMarkdownファイルとしてまとめたもの。
• metadata.json — タイトル、著者、言語、識別子、出版社、EPUBバージョン、チャプター数。

実行方法

このスキルにはscripts/run.shというランナーが付属しており、epub2md CLIを見つけてすべての引数を転送します。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はPATH上にPandocがある場合はそれを使用し、ない場合は純粋なPythonコンバーターにフォールバックします。

よくあるレシピ

1つの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

スパインによるグループ化を強制

目次が欠落、不正、または誤解を招く場合に使用します。

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モードはそれを使用します。目次の各トップレベルエントリが1つのチャプターになります。チャプターは、そのエントリの開始ファイルから次のエントリの開始ファイルまでのすべてのスパインドキュメントを含みます。これにより、複数のXHTMLファイルにまたがるチャプターが再結合されます。
• 目次がない場合、ツールはスパインにフォールバックします。各スパインドキュメントが1つのチャプターになります。
• 最初の目次エントリより前にスパインに現れる前付は、1つの「前付」チャプターとしてグループ化されます。

エラーハンドリング

• container.xmlまたはOPFがない場合: ツールは明確なメッセージを表示して終了します。EPUBが無効です。
• 不正なXHTMLフラグメント: 寛容なモードで解析されます。フラグメントの変換に失敗した場合は、生のHTMLがフェンスブロックに埋め込まれるため、コンテンツが失われることはありません。
• 参照されている画像がない場合: 警告を出力し、Markdown出力に元のsrcを保持します。
• Pandocがインストールされていない場合: ツールは自動モードでmarkdownifyにサイレントにフォールバックします。

参考資料

• references/spec.md — 完全な仕様、グループ化アルゴリズム、出力レイアウト。
• references/troubleshooting.md — 一般的なEPUB変換の問題に対する実用的な修正。