markdown-to-epub

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

markdown-to-epub Skill

把 Markdown 手稿（含本地图片）稳定构建为 EPUB：规范化图片引用、拷贝资产到可重复的构建目录、调用 Calibre

ebook-convert

转换，并输出可核查报告。

Stably build Markdown manuscripts (including local images) into EPUB: Normalize image references, copy assets to a reproducible build directory, call Calibre

ebook-convert

for conversion, and output a verifiable report.

When to Use This Skill

触发条件（满足其一即可）：

需要把一份（或多份）Markdown 手稿打包交付为 EPUB。
图片引用混乱（URL 编码、路径飘忽、扩展名不可信如
```
.bin/.idunno
```
），需要自动归一化。
需要在转换后做最基本的 EPUB 包结构检查（OPF/NCX/NAV、图片数量等）。

Trigger conditions (meet any one):

Need to package one (or multiple) Markdown manuscripts into EPUB for delivery.
Image references are messy (URL encoded, unstable paths, untrusted extensions like
```
.bin/.idunno
```
), requiring automatic normalization.
Need to perform basic EPUB package structure checks (OPF/NCX/NAV, number of images, etc.) after conversion.

Not For / Boundaries

不负责生成/改写正文内容（不会修改源手稿，只在构建目录里产出规范化版本）。
不下载远程图片（
```
http(s)
```
/
```
data:
```
引用会保持原样）。
不替代真正的排版/校对流程（这里只做可交付构建与结构验证）。

Does not generate/rewrite content (will not modify the source manuscript, only produce a normalized version in the build directory).
Does not download remote images (references with
```
http(s)
```
/
```
data:
```
will remain unchanged).
Does not replace real typesetting/proofreading processes (only delivers build and structure verification here).

Quick Start

从仓库根目录执行（推荐

python3

）：

bash

python3 skills/05-生产力/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --title "Book Title" \
  --authors "Author Name" \
  --language "zh-CN"

脚本会创建构建工作区（默认

build_epub/

），包含：

```
book.normalized.md
```
```
assets/
```
：拷贝后的图片（会按真实文件签名推断扩展名）
```
conversion.log
```
```
report.json
```

Execute from the root directory of the repository (recommended

python3

bash

python3 skills/05-生产力/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --title "Book Title" \
  --authors "Author Name" \
  --language "zh-CN"

The script will create a build workspace (default

build_epub/

) containing:

```
book.normalized.md
```
```
assets/
```
: Copied images (extensions will be inferred based on real file signatures)
```
conversion.log
```
```
report.json
```

依赖

Dependencies

需要安装 Calibre，并确保
```
ebook-convert
```
在
```
PATH
```
中（或用
```
--ebook-convert-bin
```
指定路径）。

Calibre needs to be installed, and ensure
```
ebook-convert
```
is in the
```
PATH
```
(or specify the path with
```
--ebook-convert-bin
```
).

Missing Asset Recovery

如果 Markdown 里引用了图片但文件找不到，可以提供一个 JSON 映射表（按「basename」匹配）：

json

{
  "missing-file.idunno": "replacement-file.idunno"
}

然后重跑（示例）：

bash

python3 skills/05-生产力/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --fallback-map "./fallback-map.json"

If images referenced in Markdown cannot be found, you can provide a JSON mapping table (matching by "basename"):

json

{
  "missing-file.idunno": "replacement-file.idunno"
}

Then re-run (example):

bash

python3 skills/05-生产力/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --fallback-map "./fallback-map.json"

Operational Rules

优先使用
```
ebook-convert
```
；缺失时明确报错并快速失败。
源手稿只读；所有输出写入
```
build_dir/
```
。
TOC 以标题层级（
```
h1/h2/h3
```
）为准。
缺失资产必须显式报告；严格模式下不允许静默跳过。
命令保持非交互式。

Prioritize using
```
ebook-convert
```
; explicitly report an error and fail fast if missing.
Source manuscripts are read-only; all outputs are written to
```
build_dir/
```
.
TOC is based on title levels (
```
h1/h2/h3
```
).
Missing assets must be explicitly reported; silent skipping is not allowed in strict mode.
Commands remain non-interactive.

Script Interface

scripts/build_epub.py

参数：

```
--input-md
```
（必选）：源 Markdown 路径
```
--output-epub
```
（可选）：输出 EPUB 路径，默认
```
<input-stem>.epub
```
```
--source-root
```
（可选）：解析图片引用的根目录，默认使用 Markdown 所在目录
```
--build-dir
```
（可选）：构建工作区目录，默认
```
<cwd>/build_epub
```
```
--fallback-map
```
（可选）：JSON 映射（缺失图片 basename → 替换 basename）
```
--title
```
/
```
--authors
```
/
```
--language
```
：传给
```
ebook-convert
```
的元数据
```
--input-encoding
```
：输入 Markdown 编码，默认
```
utf-8
```
```
--strict-missing
```
：严格模式（有任何本地图片无法解析则失败，默认开启）
```
--no-strict-missing
```
：关闭严格模式（保留未解析链接，继续转换）

--ebook-convert-bin

：

ebook-convert

可执行文件名/路径，默认

ebook-convert

Parameters for

scripts/build_epub.py

```
--input-md
```
(required): Path to source Markdown
```
--output-epub
```
(optional): Path to output EPUB, default is
```
<input-stem>.epub
```
```
--source-root
```
(optional): Root directory for resolving image references, default is the directory where the Markdown file is located
```
--build-dir
```
(optional): Build workspace directory, default is
```
<cwd>/build_epub
```
```
--fallback-map
```
(optional): JSON mapping (missing image basename → replacement basename)
```
--title
```
/
```
--authors
```
/
```
--language
```
: Metadata passed to
```
ebook-convert
```
```
--input-encoding
```
: Encoding of input Markdown, default is
```
utf-8
```
```
--strict-missing
```
: Strict mode (fails if any local image cannot be resolved, enabled by default)
```
--no-strict-missing
```
: Disable strict mode (retain unresolved links and continue conversion)

--ebook-convert-bin

: Executable name/path of

ebook-convert

, default is

ebook-convert

Validation Checklist

确认 EPUB 文件生成且大小不是「几 KB 的空壳」。
确认 EPUB（zip）内包含 OPF 与 NCX/NAV。
确认 EPUB 内图片数量不低于对手稿的预期。
严格模式下确认
```
report.json
```
的
```
missing_images
```
为空。

Confirm that the EPUB file is generated and its size is not an "empty shell of a few KB".
Confirm that the EPUB (zip) contains OPF and NCX/NAV.
Confirm that the number of images in the EPUB is not lower than expected from the manuscript.
In strict mode, confirm that
```
missing_images
```
in
```
report.json
```
is empty.