mark-epub-down

EPUB-to-Markdown CLI and Node.js package for LLM knowledge bases, wikis, and related ingestion workflows.

Why

This project focuses on producing semantically useful Markdown from EPUB input. The v1 goal is not visual EPUB reproduction. It prioritizes source order, document structure, TOC preservation, and conservative transformation rules.

The target output is text-first Markdown for LLM knowledge bases, wikis, and related ingestion workflows. In many current ingestion setups, preserving raw image assets or Markdown image links does not reliably produce usable downstream image understanding, while it does add complexity and processing cost. For that reason, v1 keeps image extraction opt-in instead of making it part of the default output path.

What v1 Does

• converts one EPUB into one Markdown file
• preserves spine order and source heading structure
• emits a dedicated ## TOC section from EPUB-native TOC data
• includes minimal OPF-derived YAML front matter
• rewrites internal targets conservatively for merged single-file output
• can optionally extract internal images into co-located or split per-output asset directories and emit Markdown image links

What v1 Does Not Do

• visually reproduce EPUB layout or CSS
• guess missing structure aggressively
• optimize first for reader-specific Markdown rendering
• split output by chapter in the v1 baseline

Requirements

• Node.js 20, 22, or 24
• npm

Install

Install the CLI globally:

npm install -g mark-epub-down

Or add the package to a Node.js project:

npm install mark-epub-down

The GitHub repository also includes Claude Code skill and subagent definitions plus a Codex skill source. These are documented separately in docs/agent-skills.md and are not part of the published npm package.

CLI Usage

Convert an EPUB:

epub2llm input.epub

Write to an explicit output path:

epub2llm input.epub -o output.md

Extract internal images into a co-located asset directory:

epub2llm input.epub --extract-images

Extract internal images into split sources/ and assets/ roots:

epub2llm input.epub --extract-images --output-layout=split --split-root raw

Run without global install:

npx --package mark-epub-down epub2llm input.epub

Show CLI help:

epub2llm --help

Existing output files are never overwritten silently. In an interactive terminal session, the CLI may ask for explicit overwrite confirmation with a default No answer.

When image extraction is enabled, the tool treats the Markdown file and asset directory as one logical output set for overwrite checks.

--output-layout only applies when image extraction is enabled. It does not change the Markdown-only default output path.

When --output-layout=split is used, --split-root sets the sibling sources/ and assets/ roots. If you use -o instead, the output path must live under a sources/ directory so the matching asset namespace can be mirrored under assets/.

Node API

The published package currently exposes a CommonJS API:

const { convertEpub } = require("mark-epub-down");

(async () => {
  const result = await convertEpub({
    inputPath: "input.epub",
    outputPath: "output.md",
    extractImages: "all",
  });

  console.log(result.outputPath);
  console.log(result.assetOutputPath);
  console.log(result.warnings);
})();

Split layout is also available through the Node API:

(async () => {
  await convertEpub({
    inputPath: "input.epub",
    extractImages: "all",
    outputLayout: "split",
    splitRootDir: "raw",
  });
})();

If the output path already exists, convertEpub() throws unless overwrite: true is passed:

(async () => {
  await convertEpub({
    inputPath: "input.epub",
    outputPath: "output.md",
    overwrite: true,
  });
})();

Output Shape

The generated Markdown follows this high-level structure:

---
title: Example Book
creator: Example Author
language: en
published: 2026-04-09
---

# Example Book

## TOC

- [Chapter 1](#...)
- Chapter 2

## Chapter 1

...

With optional image extraction enabled, the output set becomes:

output.md
output.assets/

Markdown image links are written relative to output.md.

With split layout enabled, the output set becomes:

raw/
  sources/
    output.md
  assets/
    output/

Nested subpaths under sources/ are mirrored under assets/, and Markdown image links are written relative to the final Markdown file location.

In split layout, these image links use standard relative filesystem paths from the final Markdown file to the mirrored asset namespace. Some Markdown tools may impose their own preview or workspace-root restrictions on multi-level ../ image paths; that tool-specific behavior is outside this project's output contract.

Docs

• Public v1 spec: docs/epub-to-md-v1-public-spec.md
• Technical selection notes: docs/v1-technical-selection.md
• Agent skill setup: docs/agent-skills.md

Limitations

• Fixed Layout EPUB (FXL) is out of scope for the v1 baseline
• some internal links or TOC targets may degrade to plain text when they cannot be rewritten safely
• complex tables may remain as HTML instead of being flattened into incorrect Markdown
• images are removed by default in v1 as a deliberate text-first ingestion boundary; optional image extraction currently targets internal raster image resources, including common SVG-wrapped cover or full-page image cases
• audio, video, CSS background images, and general vector SVG output are not part of the current v1 image-extraction path
• output files are never overwritten silently; interactive terminal use may ask for explicit confirmation

Roadmap

• expand real-world sample coverage for malformed or inconsistent EPUB inputs
• refine deeper footnote and note-topology edge cases beyond explicit source anchors
• refine richer table fallback boundaries for more complex publisher markup

Development

npm install
npm run build
npm run typecheck
npm test