vibe-coding-cn/skills/markdown-to-epub/SKILL.md

name, description

name	description
markdown-to-epub	Markdown to EPUB build skill: normalize local image references, copy assets, call Calibre ebook-convert, inspect EPUB package structure, and report missing images. Use when turning Markdown manuscripts into reproducible EPUB files.

markdown-to-epub Skill

Use this skill to build a reproducible EPUB from Markdown manuscripts with local image assets, without mutating the source manuscript.

When to Use This Skill

Trigger when any of these applies:

• Converting one or more Markdown files into an EPUB deliverable.
• Normalizing broken or inconsistent image references before conversion.
• Recovering local assets with unreliable extensions such as .bin or .idunno.
• Running Calibre ebook-convert non-interactively from a repeatable build directory.
• Checking the resulting EPUB archive for OPF, NCX/NAV, and image inclusion.

Not For / Boundaries

• Not for authoring, rewriting, proofreading, or typesetting the manuscript body.
• Not for downloading remote http(s) or data: images; remote references are preserved unless the user supplies local replacements.
• Not a substitute for full EPUB QA in dedicated readers; it performs structural and asset checks only.
• Required inputs: source Markdown path, desired EPUB path/title/authors/language, source root, and any fallback asset map.
• If Calibre is unavailable, fail clearly and provide the install/--ebook-convert-bin verification path instead of producing a fake EPUB.

Quick Reference

Common Patterns

Build a basic EPUB

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

Use a custom source root and build directory

python3 skills/markdown-to-epub/scripts/build_epub.py \
  --input-md "./manuscript/book.md" \
  --source-root "./manuscript" \
  --build-dir "./build/book-epub" \
  --output-epub "./dist/book.epub"

Recover missing assets with a fallback map

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

Allow unresolved local images but report them

python3 skills/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --no-strict-missing

Point to a non-standard Calibre binary

python3 skills/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --ebook-convert-bin "/opt/calibre/ebook-convert"

Inspect the generated package

unzip -l ./book.epub | rg 'content.opf|toc.ncx|nav.xhtml|\\.(png|jpg|jpeg|webp|gif)$'

Examples

Example 1: Clean Manuscript Build

• Input: book.md with valid local images and metadata title/author/language.
• Steps:
  1. Run the basic build command.
  2. Inspect build_epub/report.json.
  3. Check the EPUB zip listing for OPF and navigation files.
• Expected output / acceptance: book.epub exists, missing_images is empty, and package structure contains OPF plus NCX or NAV.

Example 2: Extension Recovery

• Input: Markdown references images/cover.idunno, but the file signature is a PNG.
• Steps:
  1. Run the build script in strict mode.
  2. Confirm copied assets in build_epub/assets/ use normalized extensions.
  3. Rebuild after fixing any missing file mapping.
• Expected output / acceptance: EPUB includes the normalized image and the report records no unresolved local image.

Example 3: Missing Asset Triage

• Input: manuscript references old file names that no longer exist.
• Steps:
  1. Create a JSON fallback map from missing basenames to replacement basenames.
  2. Re-run with --fallback-map.
  3. Keep strict mode enabled so unmapped missing assets fail the build.
• Expected output / acceptance: every missing local image is either resolved by the map or listed in report.json for explicit follow-up.

References

• references/index.md: navigation, script contract, and validation notes.
• scripts/build_epub.py: executable builder used by this skill.
• agents/openai.yaml: agent metadata for this skill package.

Maintenance

• Sources: local script implementation and EPUB/Calibre behavior observed by the build report.
• Last updated: 2026-04-28
• Known limits: structural checks do not guarantee visual fidelity in every EPUB reader; run reader-specific QA for final publication.