epub2md

Convert EPUB2 books into:

• A single Markdown file
• A set of image files actually referenced from the body text

The tool only supports EPUB2 with an NCX table of contents. It emphasizes "single-file reading" and "explicit chapter structure" rather than reproducing the EPUB's internal file layout. See docs/architecture.md and docs/flow.md for the maintenance-level design.

Install

Requires Node.js 18+ (Bun is not required).

# pnpm
pnpm add -g @yzlin-net/epub2md

# npm
npm i -g @yzlin-net/epub2md

Usage

epub2md book.epub

By default, this generates book.md and an images/ directory in the current directory.

Common options:

# Specify the output directory
epub2md book.epub -o ./out

# Control the heading depth to keep (0-6, default 2)
epub2md book.epub -d 3

# Use Obsidian image syntax
epub2md book.epub --image-syntax obsidian

Three operating modes

• Default mode: Generate Markdown and images directly from the EPUB.
• --emit-toc [file]: Export an editable chapter TOC JSON so you can adjust the structure by hand, for example to drop copyright pages or merge appendices.
• --toc <file>: Continue conversion with an edited TOC, while still using the original EPUB as the source of body text and images.

# Emit the TOC
epub2md book.epub --emit-toc toc.json

# Edit toc.json, then convert
epub2md book.epub --toc toc.json -o ./out

Runtime environment

• The published CLI runs in a normal Node.js environment and does not require Bun at install time.
• Local development still uses Bun (see the maintainer notes below).

For maintainers

Local development

The development toolchain is Bun:

bun install
bun test          # run tests
bun run dev       # run the source directly
bun run build     # target is node, output goes to dist/cli.js

The build artifact dist/cli.js uses #!/usr/bin/env node as its shebang and can be executed directly with node. Production code does not depend on any Bun-specific APIs. Test files still use the Bun test API, but they are not shipped in the package.

Release process

1. Confirm the npm account has publish rights for the @yzlin scope

2. Run tests: bun test

3. Run the build: bun run build

4. Run the packaging smoke check (see below)

5. Publish:

   npm publish --access public

The prepack and prepublishOnly hooks rebuild automatically before npm pack and npm publish, so even a package created from a clean checkout still contains the latest dist/cli.js.

Packaging smoke check

Before releasing, confirm the package contents and executability:

bun run build
npm pack
tar -tzf yzlin-net-epub2md-*.tgz   # should only include dist/, README.md, LICENSE, and package.json
npm i -g yzlin-net-epub2md-*.tgz    # or use a temp prefix: npm i --prefix /tmp/probe
epub2md --help
epub2md test/fixtures/minimal.epub -o /tmp/epub2md-smoke

Success criteria:

• epub2md --help exits successfully under Node
• A real conversion completes in an environment without Bun
• The package contains only runtime files such as dist/cli.js, with no tests or source files

License

MIT