Markdown to EPUB Claude Skill

A Claude agent skill that converts markdown documents and chat summaries into professional EPUB ebook files. Perfect for creating portable, device-agnostic ebooks from research documents, blog posts, articles, or conversation summaries.

Overview

This skill transforms markdown content into EPUB3 format ebooks that work across all major reading platforms:

Apple Books
Amazon Kindle (via Kindle reading apps)
Google Play Books
Kobo
Any standard EPUB reader

Features

✨ Markdown Processing

Automatic chapter detection from H1 headers
Automatic section parsing from H2-H6 headers
Full markdown formatting support (bold, italic, links, lists, code blocks, etc.)
Enhanced code blocks with premium monospace fonts and syntax highlighting support
Professional tables with styled headers and alternating row colors

📚 EPUB Generation

EPUB3 standard compliance
Automatic table of contents with proper navigation
Responsive, device-agnostic styling
Proper document structure and metadata
Beautiful code formatting for technical documents

🎯 Smart Input Handling

Accept raw markdown text directly
Process markdown files by path
Extract metadata from YAML frontmatter
Handle edge cases gracefully

Project Structure

markdown-to-epub/
├── SKILL.md                    # Skill definition with YAML frontmatter
├── requirements.txt            # Python dependencies
├── scripts/
│   ├── markdown_processor.py  # Markdown parsing & structure extraction
│   ├── epub_generator.py      # EPUB file creation & formatting
└── resources/
    └── default_styles.css     # (future) Custom EPUB styling
test_epub_skill.py             # Test suite with sample content

Installation

Prerequisites

Python 3.8+
pip (Python package manager)

Setup

Install dependencies:

BASH

pip install -r markdown-to-epub/requirements.txt

Verify installation:
BASH
```
python test_epub_skill.py
```
You should see all tests pass:
- ✓ Markdown processing: PASSED
- ✓ EPUB generation: PASSED
- ✓ Edge cases: PASSED

Usage

Basic Python Usage

PYTHON

from markdown_to_epub.scripts.epub_generator import create_epub_from_markdown

markdown_content = """
# My Book

## Chapter 1
Content here...
"""

# Generate EPUB
create_epub_from_markdown(
    markdown_content,
    output_path="my_book.epub",
    title="My Book",
    author="John Doe"
)

With Claude Skills Framework

When registered as a Claude skill, simply ask Claude to convert markdown to EPUB:

"Convert this markdown to an EPUB ebook:
# Research Summary
## Introduction
...content..."

Or provide a file path:

"Convert the markdown file at research_notes.md to an EPUB file"

Markdown Support

Element	Example	Support	Styling
Headers	`# H1` through `###### H6`	Full	Optimized sizes for e-readers
Bold	`bold` or `__bold__`	Full	Strong emphasis
Italic	`italic` or `_italic_`	Full	Subtle emphasis
Links	`[text](url)`	Full	Clickable
Lists	`- item` or `1. item`	Full	Proper indentation
Code Blocks	```language	Enhanced	Monospace fonts, styled backgrounds, blue accent
Inline Code	`code`	Enhanced	Gray background, subtle border
Tables	Markdown tables	Enhanced	Blue headers, zebra striping, responsive
Blockquotes	`> quote`	Full	Blue left border
Horizontal Rule	`---` or `***`	Full	Subtle divider
Paragraphs	Text with blank lines	Full	Justified text

YAML Frontmatter Support

Add metadata to your markdown using YAML frontmatter:

MARKDOWN

---
title: My Ebook
author: John Doe
language: en
date: 2025-01-15
---

# Chapter 1
...

Supported fields:

title - Book title
author - Author name
language - Language code (default: en)
date - Publication date

Architecture

MarkdownProcessor (`markdown_processor.py`)

Parses markdown into structured chapters and sections
Extracts metadata from YAML frontmatter
Builds table of contents
Converts markdown to HTML
Handles edge cases (empty content, special characters, etc.)

EPUBGenerator (`epub_generator.py`)

Creates valid EPUB3 files using ebooklib
Manages book metadata and document structure
Applies consistent styling via embedded CSS
Generates navigation documents (NCX, NAV)
Handles proper spine/TOC setup

Dependencies

ebooklib (0.18.0) - EPUB file creation and manipulation
markdown2 (2.4.12) - Markdown utilities (included for future enhancement)

Testing

Run the comprehensive test suite:

BASH

python test_epub_skill.py

Tests include:

Markdown parsing with various header structures
EPUB file generation and validation
Edge cases (empty content, plain text, special characters)
Long documents (10+ chapters)
Table of contents generation
Metadata extraction

Future Enhancements

🎨 Cover Page Generation

Auto-generate title pages with styling
Custom cover images with MCP integration

📱 Kindle Support

.mobi and .azw3 format generation
Kindle-specific optimizations
Direct Kindle device upload capability

🎨 Advanced Styling

Custom CSS per user preferences
Custom fonts
Advanced typography controls

📚 Multi-Document

Merge multiple markdown files
Cross-document references
Advanced chapter organization

Technical Details

EPUB Version: EPUB3 (2023 standard)
HTML Standard: XHTML 1.1
Character Encoding: UTF-8
CSS Support: Responsive, embedded styling
Navigation: NCX (compatibility) + NAV (EPUB3 standard)

Troubleshooting

EPUB won't open

Verify markdown uses proper syntax
Check for balanced brackets in links
Ensure chapters have H1 headers

Missing table of contents

Add H1 headers to mark chapter boundaries
Verify headers are followed by content

Formatting looks different

This is normal! EPUB readers apply their own fonts and styling
Structure is preserved across all readers

Large file size

Compress with external tools if needed
Remove large embedded content if applicable

License

This skill follows the same license as the Claude Cookbooks project.

Contributing

Contributions are welcome! Areas for improvement:

Additional markdown features (tables, footnotes)
Enhanced styling options
Performance optimizations
Additional format support

Created: 2025-01-16 Version: 1.0.0 Status: Production Ready