Create production-quality EPUB 3 ebooks from markdown and images with automated QA, formatting fixes, and validation. Use when creating ebooks, converting markdown to EPUB, or compiling chapters into a publishable book. Handles markdown quirks, generates TOC, adds covers, and validates output automatically.
Create validated, publication-ready EPUB 3 ebooks from markdown files and images.
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
Follow this 5-step workflow to create high-quality EPUBs:
1. PRE-PROCESS → 2. CONVERT → 3. ASSEMBLE → 4. VALIDATE → 5. DELIVER
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().
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().
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()....