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:
- 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