joeseesun EPUB Book Generator
从 Markdown 文件生成专业 EPUB 电子书，支持封面、配图压缩、目录生成。
功能特性
- ✅ 单文件或多文件 EPUB 生成
- ✅ 自动下载 Markdown 中的图片（支持 http/https URL）
- ✅ SVG 自动转换（使用 Playwright 将 SVG 转为 PNG，完美支持网页文章）
- ✅ 本地文件路径支持（支持本地图片文件直接嵌入）
- ✅ 自动图片压缩（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
工作流程
收集输入
- 扫描 Markdown 文件
- 检查配图（同名 PNG/JPG）
- 确认封面（可选）
处理内容
- 解析 Markdown（标题、元数据、正文）
- 自动下载远程图片（http/https URL）
- SVG 自动转换（使用 Playwright 渲染为 PNG）
- 本地文件嵌入（支持相对/绝对路径）
- 压缩图片（宽度 1000px，JPEG 88%）
- 构建 XHTML 章节
生成 EPUB
- 创建 EpubBook 对象
- 添加元数据（作者、语言、描述）
- 设置封面（如有）
- 生成目录（TOC）
- 写入 EPUB 文件
验证输出
- 检查文件大小
- 统计章节数
- 报告图片压缩率
参数配置
详见 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 格式
解决方案：
gen_epub_enhanced.py会自动检测 SVG 图片- 使用 Playwright 将 SVG 渲染为 PNG
- 自动替换 Markdown 中的图片链接
技术细节：
- SVG 检测：通过 URL 扩展名、Content-Type、文件头识别
- 转换方式：Playwright headless browser 渲染 + 截图
- 批处理优化：共享浏览器实例，提升转换速度
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/photo.png - 父目录：
../assets/photo.png
网页文章转 EPUB 最佳实践
场景：从技术博客（如 tw93.fun）生成 EPUB
推荐流程：
- 使用
qiaomu-markdown-proxy或baoyu-url-to-markdown下载文章 - 检查 Markdown 中的图片 URL（特别是 SVG）
- 如果有大量 SVG，可选择：
- 方案 A（推荐）：直接运行
gen_epub_enhanced.py，自动转换 - 方案 B：预先批量转换 SVG，然后替换 URL
- 方案 A（推荐）：直接运行
- 清理 blob URLs（如有）
- 生成 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