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 gather_inputs(), fix_markdown_quirks(), validate_and_fix_images(), validate_cover(), and validate_sources().

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 extract_frontmatter(), extract_title(), markdown_to_xhtml(), extract_toc_structure(), and build_nested_toc().

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 EPUB_CSS and create_production_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 validate_epub(), post_validate_epub(), and qa_checklist().

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 create_epub_production().

Usage Examples

Basic Usage

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

Claude will:

Scan for markdown files
Fix any formatting issues
Generate TOC from headings
Create styled EPUB
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

| Issue | Solution | |-------|----------| | "No markdown files found" | Ensure .md files exist in source directory | | "Cover too small" | Use image at least 1400x2100 pixels | | "Validation failed" | Check report for specific errors | | "Broken images" | Verify image paths are relative to markdown files | | "Encoding errors" | Files will be auto-converted to UTF-8 |

Tips for Best Results

Organize chapters with numbered prefixes: 01-intro.md, 02-chapter1.md
Use consistent heading levels: Start each chapter with # Title
Place images in same directory as markdown or images/ subfolder
Add YAML frontmatter for chapter metadata:
```
---
title: Chapter One
---
```
Validate before publishing with epubcheck