EPUB Creator (Production Grade)

Create validated, publication-ready EPUB 3 ebooks from markdown files and images.

Prerequisites

Python Version: Requires Python 3.8 or higher

# Install all required packages
uv pip install ebooklib markdown Pillow beautifulsoup4 lxml PyYAML

# Or with pip
pip install ebooklib markdown Pillow beautifulsoup4 lxml PyYAML

Optional (for EPUB validation):

# macOS
brew install epubcheck

# Linux (Debian/Ubuntu)
apt install epubcheck

# Via Python wrapper
uv pip install epubcheck

Production Workflow

Follow this 5-step workflow to create high-quality EPUBs:

1. PRE-PROCESS → 2. CONVERT → 3. ASSEMBLE → 4. VALIDATE → 5. DELIVER

Step 1: Pre-Processing (Input Validation & Fixes)

Gather inputs, fix markdown quirks (line endings, heading levels, unclosed emphasis, broken links), validate and optimize images, and validate cover dimensions (minimum 1400x2100px, ~1:1.5 aspect ratio).

See references/pre-processing.md for full implementation with gatherinputs(), fixmarkdownquirks(), validateandfiximages(), validatecover(), and validatesources().

Step 2: Content Conversion

Extract YAML frontmatter metadata, smart-extract chapter titles (frontmatter > first heading > filename), convert markdown to valid EPUB XHTML with robust extensions (tables, fenced code, smart quotes, sane lists), and build hierarchical ToC structure with configurable depth (H1/H2/H3).

See references/content-conversion.md for full implementation with extractfrontmatter(), extracttitle(), markdowntoxhtml(), extracttocstructure(), and buildnestedtoc().

Step 3: EPUB Assembly

Apply professional CSS stylesheet (typography, headings, paragraphs, code blocks, tables, images), build the complete EPUB with ebooklib including metadata, cover, chapters, images, TOC, and spine.

See references/epub-assembly.md for full implementation with EPUBCSS and createproduction_epub().

Step 4: Validation & QA

Run epubcheck (with fallback to basic ZIP structure validation), comprehensive post-validation (file size, mimetype, container.xml, XHTML content, styles, images), and a QA checklist summarizing pass/fail/warnings.

See references/validation-qa.md for full implementation with validateepub(), postvalidateepub(), and qachecklist().

Step 5: Complete Production Script

End-to-end orchestration: auto-detect cover, create EPUB, run QA, print report, save JSON report alongside the EPUB.

See references/production-script.md for full implementation with createepubproduction().

Usage Examples

Basic Usage

"Create an EPUB from the markdown files in ./chapters"

Claude will:

1. Scan for markdown files
2. Fix any formatting issues
3. Generate TOC from headings
4. Create styled EPUB
5. Validate and report

With Cover Image

"Create an EPUB called 'My Novel' from ./book with cover.jpg as the cover"

Full Metadata

"Create an EPUB from ./manuscript:
- Title: The Great Adventure
- Author: Jane Smith
- Language: English
- Publisher: Indie Press"

QA Mode

"Create an EPUB from ./draft and show me all the issues found"

Troubleshooting

Tips for Best Results

1. Organize chapters with numbered prefixes: 01-intro.md, 02-chapter1.md
2. Use consistent heading levels: Start each chapter with # Title
3. Place images in same directory as markdown or images/ subfolder
4. Add YAML frontmatter for chapter metadata:

```yaml

title: Chapter One

```

1. Validate before publishing with epubcheck