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: bash pip install -r markdown-to-epub/requirements.txt

2. 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

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

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

📚 Мульти-документ - Объединять несколько markdown-файлов - Перекрестные ссылки между документами - Расширенная организация глав

Технические детали

• EPUB Version: EPUB3 (стандарт 2023)
• HTML Standard: XHTML 1.1
• Кодировка символов: UTF-8
• Поддержка CSS: Адаптивное, встроенное стилевое оформление
• Навигация: NCX (совместимость) + NAV (стандарт EPUB3)

Устранение неполадок

EPUB не открывается - Проверьте, что markdown использует правильный синтаксис - Проверьте сбалансированность скобок в ссылках - Убедитесь, что главы имеют заголовки H1

Отсутствует оглавление - Добавьте заголовки H1 для обозначения границ глав - Проверьте, что после заголовков следует содержимое

Форматирование выглядит иначе - Это нормально! Читалки EPUB применяют свои шрифты и стили - Структура сохраняется во всех читалках

Большой размер файла - При необходимости сжимайте с помощью внешних инструментов - При наличии удаляйте большие встроенные материалы

Лицензия

Этот навык использует ту же лицензию, что и проект Claude Cookbooks.

Вклад

Приветствуются вклад! Области для улучшения: - Дополнительные возможности markdown (таблицы, сноски) - Расширенные возможности стилизации - Оптимизация производительности - Поддержка дополнительных форматов

Связанные ресурсы

• Стандарт EPUB 3
• Документация по навыкам Claude
• Документация ebooklib
• Синтаксис markdown

Создан: 2025-01-16 Версия: 1.0.0 Статус: Готов к работе