markdown-to-epub

Original：🇨🇳 Chinese

Translated

1 scripts

Convert Markdown manuscripts and local image assets into verifiable EPUB: Fix/normalize image references and extensions, maintain title-level TOC, and perform basic package structure checks.

1installs

Sourcetukuaiai/vibe-coding-cn

Added on2026-02-21

NPX Install

npx skill4agent add tukuaiai/vibe-coding-cn markdown-to-epub

SKILL.md Content (Chinese)

View Translation Comparison →

markdown-to-epub Skill

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

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

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

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 needs to be installed, and ensure
```
ebook-convert
```
is in the
```
PATH
```
(or specify the path with
```
--ebook-convert-bin
```
).

Missing Asset Recovery

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

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

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

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.