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

1. Install dependencies:

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

2. Verify installation:

   python test_epub_skill.py
   

   You should see all tests pass:

   • ✓ Markdown processing: PASSED
   • ✓ EPUB generation: PASSED
   • ✓ Edge cases: PASSED

Usage

Basic Python Usage

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:

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

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

Related Resources

• EPUB 3 Standard
• Claude Skills Documentation
• ebooklib Documentation
• Markdown Syntax

---

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