Skip to content

README_zh.md

Latest commit

 

History

History
174 lines (130 loc) · 6.74 KB

README_zh.md

File metadata and controls

174 lines (130 loc) · 6.74 KB

epub2md

将 EPUB 电子书按章节目录拆分为独立的 Markdown 文件，保留多级目录结构。

为什么要开发这个技能？

对数以亿计的中国和亚洲读者来说，阅读英文 EPUB 电子书是语言学习的核心环节。但阅读体验一直很痛苦：你在电子书和词典之间来回切换，把段落复制粘贴到翻译工具里，然后反复找不到之前读到哪了——周而复始。

epub2md 就是为了改变这种体验而生。将 EPUB 拆分为按章节的 Markdown 文件后，阅读流程会发生根本变化：

  • 直接将章节喂给 AI — 把一个章节丢进 Claude、ChatGPT 或任何大语言模型，即可获得即时翻译、词汇批注或双语对照。再也不用从笨拙的电子阅读器里复制粘贴。
  • 双语交替阅读 — Markdown 天然适合生成段对段的双语文本（原文 + 译文），这正是大多数亚洲学习者的实际阅读方式：先读英文段落，下方紧跟中文翻译，循环往复。这种交替节奏让你始终沉浸在阅读流中，而不用在标签页之间跳来跳去。
  • 章节粒度的上下文控制 — 大语言模型有上下文限制。按章节拆分意味着每个片段的大小恰好适合高质量 AI 辅助——不截断、不遗漏、不会因为塞入过多内容而产生幻觉。
  • Markdown 作为通用格式 — 笔记、高亮和 AI 批注直接与正文共存。在 Obsidian、VS Code 或任何 Markdown 编辑器中编辑，用 Git 版本控制你的学习笔记。格式完全属于你自己。

简而言之：epub2md 将一本锁在电子书里的书，转化为面向学习者、面向 AI、原生 Markdown 的学习工具包。

特性

  • 零依赖 — 仅使用 Python 标准库（zipfile、html.parser、re、json 等），无需 pip install
  • 目录感知拆分 — 读取 NCX（EPUB2）和 NAV（EPUB3）目录结构，构建章节层级
  • 目录结构映射 — 根据书籍的章节层级创建嵌套文件夹
  • 图片提取 — 将所有图片保存到 images/ 目录，并自动修正 Markdown 中的相对路径引用
  • 智能标题增强 — 自动丰富贫瘠标题（如 "1"、"Part II"），从 HTML 内容中提取描述性文字合并
  • Spine 回退 — 无目录时回退到 OPF spine 顺序，从 HTML 标题中提取真实章节名
  • 清单追踪 — 生成 manifest.json，包含完整的章节元数据，便于进度追踪和断点续传

使用方法

命令行

python scripts/epub2md.py <input.epub> [--output-dir <dir>]
  • <input.epub> — EPUB 文件路径
  • --output-dir — 输出目录（默认在 EPUB 同级目录下创建以书名命名的文件夹）

Claude Code Skill

本项目同时是一个 Claude Code skill。

安装 Skill

将本仓库克隆到 Claude Code 的 skills 文件夹中：

# macOS / Linux
git clone https://github.com/AdkinsHan/epub2md.git ~/.claude/skills/epub2md

# Windows (PowerShell)
git clone https://github.com/AdkinsHan/epub2md.git "$env:USERPROFILE\.claude\skills\epub2md"

如果已经克隆到其他位置，也可以直接复制：

# macOS / Linux
cp -r /path/to/epub2md ~/.claude/skills/epub2md

# Windows (PowerShell)
Copy-Item -Recurse "D:\path\to\epub2md" "$env:USERPROFILE\.claude\skills\epub2md"

重启 Claude Code 或重新加载会话——/epub2md 命令将自动可用。

使用 Skill

在 Claude Code 会话中，输入：

/epub2md <书籍路径.epub>

Skill 会自动：

  1. 验证并解析 EPUB 文件路径
  2. 运行 Python 脚本拆分 EPUB 为章节
  3. 展示章节列表和输出结构供审查
  4. 验证输出结果

你也可以指定自定义输出目录：

/epub2md /path/to/book.epub --output-dir /path/to/output

或者在对话中提及 EPUB 文件——Skill 会在检测到 "EPUB"、"epub转markdown"、"拆分电子书" 等关键词时自动触发。

输出结构

以 MyBook.epub 为例，输出如下：

MyBook/
├── 001_Foreword.md
├── 002_Chapter One/
│   ├── 002_Chapter One.md
│   ├── 003_Section 1.1.md
│   └── 004_Section 1.2.md
├── 005_Chapter Two/
│   ├── 005_Chapter Two.md
│   └── 006_Section 2.1.md
├── images/
│   ├── cover.png
│   ├── fig1.jpg
│   └── fig2.png
└── manifest.json

Markdown 文件中的图片引用使用正确的相对路径（根级章节为 images/cover.png，嵌套章节为 ../images/cover.png）。

清单格式

manifest.json 包含：

{
  "source_file": "MyBook.epub",
  "book_title": "My Book",
  "output_dir": "/path/to/MyBook",
  "total_chapters": 6,
  "attachments_dir": "images",
  "image_count": 3,
  "chapters": [
    {
      "index": 0,
      "title": "Foreword",
      "src": "foreword.xhtml",
      "dir_path": "",
      "filename": "001_Foreword.md",
      "full_path": "/path/to/MyBook/001_Foreword.md",
      "level": 0,
      "status": "done"
    }
  ]
}

HTML 转 Markdown

支持常见的 EPUB HTML 元素：

HTML Markdown
<h1>–<h6> #–######
<p> 段落（空行分隔）
<strong>, <b> **粗体**
<em>, <i> *斜体*
<code> `行内代码`
<pre> 围栏代码块
<ul>, <ol>, <li> - 列表项 / 1. 列表项
<blockquote> > 引用
<a> [文本](链接)
<img> ![替代文本](图片路径)
<hr> ---
<dl>, <dt>, <dd> 定义列表
<sup>, <sub> ^上标, ~下标
HTML 实体 Unicode 字符

不足与注意事项

  • 不支持表格 — HTML <table> 元素会被原样保留或去除，复杂表格无法正确转换为 Markdown 格式。
  • 丢失 CSS 样式 — 字体大小、颜色、分栏布局等 CSS 驱动的排版格式在转换后会丢失。
  • 脚注与尾注 — EPUB 中的脚注链接和反向引用不会转换为 Markdown 脚注语法（[^1]），而是变为普通链接。
  • SVG 图片 — 仅提取栅格图片（PNG、JPG 等），不支持 SVG 和内嵌 base64 图片。
  • DRM 加密文件 — 带有数字版权保护的 EPUB 无法打开，本工具仅适用于无 DRM 的 EPUB 文件。
  • 编码边界情况 — 脚本会依次尝试 UTF-8、GBK 和 Latin-1，但某些罕见编码的 EPUB 可能出现乱码，需检查输出。
  • 合并章节 — 部分 EPUB 将多个逻辑章节合并在一个 HTML 文件中，脚本按目录条目拆分而非按内部标题拆分，因此这些内容会作为一个长章节输出。
  • 非电子书阅读器 — 本工具专注于提取和转换，不支持阅读。无法保留原 EPUB 的阅读位置、书签或批注。

许可证

Apache License 2.0