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 PyYAMLOptional (for EPUB validation):
# macOS
brew install epubcheck
# Linux (Debian/Ubuntu)
apt install epubcheck
# Via Python wrapper
uv pip install epubcheckProduction Workflow
Follow this 5-step workflow to create high-quality EPUBs:
1. PRE-PROCESS → 2. CONVERT → 3. ASSEMBLE → 4. VALIDATE → 5. DELIVERStep 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