qiaomu-epub-book-generator

EPUB 書籍ジェネレーター

Markdown ファイルから、表紙、画像の圧縮、目次の生成に対応したプロフェッショナルな EPUB 電子書籍を生成します。

機能

• ✅ 単一ファイルまたは複数ファイルから EPUB を生成
• ✅ Markdown 内の画像を自動ダウンロード（http/https URL に対応）
• ✅ SVG を自動変換（Playwright で SVG を PNG に変換し、Web 記事に完全対応）
• ✅ ローカルファイルパスに対応（ローカル画像ファイルを直接埋め込み可能）
• ✅ 画像を自動圧縮（PNG→JPEG、品質を設定可能）
• ✅ 完全な Markdown レンダリング（コードブロック、表、リストなど）
• ✅ プロフェッショナルな書籍表紙デザイン（出版業界のベストプラクティスに準拠）
  • HTML 表紙：すばやく生成でき、ほとんどの用途に適しています
  • SVG 表紙：KDP 標準サイズ（1600x2560）、プロフェッショナルな組版
  • 6 種類のスマートテーマ：tech, business, design, literature, science, personal
  • 3 種類のレイアウトスタイル：minimal, classic, modern
• ✅ 目次（TOC）を自動生成
• ✅ 微信读书互換モード
• ✅ 中国語フォントに最適化された組版

使用方法

⚠️ 表紙の生成ルール（重要）

デフォルトの動作：

• ユーザーが書名（--title）または著者（--author）を指定した場合、表紙を自動生成する必要があります
• デフォルトでは --cover-svg パラメーターを使用します（KDP 標準サイズ、プロフェッショナルな組版）
• サブタイトル（--subtitle）は省略可能で、デフォルトは "N articles" です
• テーマは自動検出されますが、--cover-theme で手動指定することもできます

表紙の生成方法の選択：

方法	パラメーター	サイズ	適した用途
SVG（推奨）	--cover-svg	1600x2560 (KDP)	プロフェッショナルな出版、高品質な表紙
HTML	--cover-html	1600x2560	すばやい生成、優れた互換性
カスタム画像	--cover path.jpg	任意	ユーザーが独自にデザインした表紙

例外：

• ユーザーが「表紙なし」または「表紙は不要」と明示した場合 → 生成しません
• ユーザーが表紙画像のパス（--cover）を指定した場合 → ユーザーの表紙を使用します

コマンドテンプレート：

# SVG 封面（推荐，KDP 标准）
python3 gen_epub_enhanced.py <input_dir> <output.epub> \
  --title "书名" \
  --author "作者" \
  --cover-svg \
  --subtitle "副标题（可选）" \
  --cover-theme "tech" \
  --cover-layout "minimal"

# HTML 封面
python3 gen_epub_enhanced.py <input_dir> <output.epub> \
  --title "书名" \
  --author "作者" \
  --cover-html \
  --subtitle "副标题（可选）"

使用可能なテーマ：tech, business, design, literature, science, personal（タイトルの内容に基づいて自動検出） 使用可能なレイアウト（SVG のみ）：minimal, classic, modern

基本的な使い方

生成 EPUB：
- 输入目录：~/articles/
- 输出：~/output.epub
- 自动生成封面（如果有书名/作者）

カスタム表紙を指定する

生成带封面的 EPUB：
- 文章：~/articles/*.md
- 封面：~/cover.jpg
- 输出：~/book.epub

表紙を自動生成する（推奨）

生成 EPUB 并设计封面：
- 书名：《我的书》
- 副标题：精选文章合集
- 作者：向阳乔木
- 风格：Mondo 极简主义

実例：

生成马斯克传记电子书：
- 书名：《埃隆·马斯克传》
- 副标题：从南非少年到世界首富的传奇人生
- 作者：向阳乔木
- 章节：10 章（01-南非少年.md 到 10-首富人生.md）
- 输出：0.2 MB，兼容微信读书和 Apple Books

ワークフロー

1. 入力を収集

   • Markdown ファイルをスキャン
   • 挿絵を確認（同名の PNG/JPG）
   • 表紙を確認（省略可能）

2. コンテンツを処理

   • Markdown を解析（タイトル、メタデータ、本文）
   • リモート画像を自動ダウンロード（http/https URL）
   • SVG を自動変換（Playwright で PNG にレンダリング）
   • ローカルファイルを埋め込み（相対パス／絶対パスに対応）
   • 画像を圧縮（幅 1000px、JPEG 88%）
   • XHTML 章を構築

3. EPUB を生成

   • EpubBook オブジェクトを作成
   • メタデータを追加（著者、言語、説明）
   • 表紙を設定（指定されている場合）
   • 目次（TOC）を生成
   • EPUB ファイルを書き込み

4. 出力を検証

   • ファイルサイズを確認
   • 章数を集計
   • 画像の圧縮率を報告

パラメーター設定

詳しくは references/config-spec.md を参照してください。

スクリプトの説明

• scripts/gen_epub_enhanced.py - 推奨 拡張版（画像の自動ダウンロード + SVG 変換 + ローカルファイル対応 + 完全な Markdown レンダリング）
• scripts/gen_epub.py - 基本的な EPUB 生成（ローカル画像の照合方式）
• scripts/gen_epub_v2.py - 微信读书互換版
• scripts/gen_epub_with_cover.py - 表紙付きバージョン
• scripts/gen_cover.py - Mondo スタイルの表紙生成

よくある問題と解決方法

SVG 画像が表示されない問題

症状：生成された EPUB で SVG 画像が表示されない

原因：ほとんどの EPUB リーダーは SVG 形式に対応していません

解決方法：

1. gen_epub_enhanced.py が SVG 画像を自動検出します
2. Playwright を使用して SVG を PNG にレンダリングします
3. Markdown 内の画像リンクを自動的に置き換えます

技術的な詳細：

• SVG の検出：URL の拡張子、Content-Type、ファイルヘッダーから判定
• 変換方法：Playwright のヘッドレスブラウザーでレンダリングし、スクリーンショットを撮影
• バッチ処理の最適化：ブラウザーインスタンスを共有して変換速度を向上

Blob URL の問題

症状：スクリプトが停止する、または "unknown url type: blob:" というエラーが発生する

原因：Markdown に blob:http://localhost/... などのブラウザーのメモリー上の URL が含まれており、ダウンロードできません

解決方法：

# 清理 blob URLs
sed -i '' '/!\[.*\](blob:http:\/\/localhost\//d' your-article.md

ローカルファイルパスへの対応

使い方：Markdown 内でローカル画像パスを直接使用できます

![本地图片](./images/photo.png)
![绝对路径](/tmp/converted/image.jpg)

対応しているパス形式：

• 相対パス：./images/photo.png
• 絶対パス：/tmp/photo.png
• 親ディレクトリ：../assets/photo.png

Web 記事を EPUB 化するためのベストプラクティス

用途：技術ブログ（tw93.fun など）から EPUB を生成する

推奨ワークフロー：

1. qiaomu-markdown-proxy または baoyu-url-to-markdown を使用して記事をダウンロードします
2. Markdown 内の画像 URL（特に SVG）を確認します
3. SVG が多数ある場合は、次のいずれかを選択できます：
   • 方法 A（推奨）：gen_epub_enhanced.py を直接実行し、自動変換します
   • 方法 B：事前に SVG を一括変換してから、URL を置き換えます
4. blob URL を削除します（含まれている場合）
5. EPUB を生成します

実例：

# Tw93 技术文集（4 篇文章，33 个 SVG 图片）
python3 gen_epub_enhanced.py /tmp/tw93_articles/ output.epub \
  --title "Tw93技术文集" \
  --author "Tw93" \
  --image-width 1000 \
  --image-quality 88

# 输出：2.8 MB，53 张图片（33 SVG→PNG + 20 其他）

例

詳しくは references/examples.md を参照してください。