Markdown to EPUB Conversion

A document conversion skill for transforming Markdown, HTML, and other text formats into EPUB ebooks, PDFs, and other publication formats using Pandoc and custom conversion pipelines.

When to Use

Choose Markdown EPUB Conversion when:

• Converting Markdown documentation into publishable EPUB or PDF ebooks
• Building automated documentation-to-ebook pipelines
• Creating multi-chapter books from Markdown source files
• Generating formatted publications with cover images, TOC, and metadata

Consider alternatives when:

• Writing and editing books — use dedicated writing software like Scrivener
• Simple PDF export — use a Markdown editor's built-in PDF export
• Publishing to web — convert to HTML with a static site generator

Quick Start

Copy
# Install Pandoc
brew install pandoc  # macOS
# or: sudo apt install pandoc  # Ubuntu

# Basic Markdown to EPUB conversion
pandoc input.md -o output.epub --metadata title="My Book"

# Multi-file book with TOC and cover
pandoc chapter1.md chapter2.md chapter3.md \
  -o book.epub \
  --toc --toc-depth=2 \
  --epub-cover-image=cover.jpg \
  --metadata-file=metadata.yaml \
  --css=epub-style.css

Copy
import subprocess
import yaml
from pathlib import Path

class EbookBuilder:
    def __init__(self, project_dir):
        self.project_dir = Path(project_dir)
        self.chapters = []
        self.metadata = {}

    def add_chapter(self, filepath):
        self.chapters.append(self.project_dir / filepath)

    def set_metadata(self, title, author, language='en', **kwargs):
        self.metadata = {
            'title': title,
            'author': author,
            'language': language,
            'date': kwargs.get('date', ''),
            'rights': kwargs.get('rights', 'All rights reserved'),
            'description': kwargs.get('description', ''),
            'publisher': kwargs.get('publisher', ''),
            'cover-image': kwargs.get('cover', '')
        }

    def build_epub(self, output_path):
        meta_file = self.project_dir / 'metadata.yaml'
        with open(meta_file, 'w') as f:
            yaml.dump(self.metadata, f)

        cmd = [
            'pandoc',
            *[str(c) for c in self.chapters],
            '-o', output_path,
            '--metadata-file', str(meta_file),
            '--toc', '--toc-depth=2',
            '--epub-chapter-level=1',
            '--css', str(self.project_dir / 'style.css'),
        ]

        if self.metadata.get('cover-image'):
            cmd.extend(['--epub-cover-image', self.metadata['cover-image']])

        result = subprocess.run(cmd, capture_output=True, text=True)
        if result.returncode != 0:
            raise Exception(f"Pandoc error: {result.stderr}")
        return output_path

    def build_pdf(self, output_path):
        cmd = [
            'pandoc',
            *[str(c) for c in self.chapters],
            '-o', output_path,
            '--toc',
            '--pdf-engine=xelatex',
            '-V', 'geometry:margin=1in',
            '-V', 'fontsize=12pt',
            '-V', 'mainfont=Times New Roman'
        ]
        subprocess.run(cmd, check=True)
        return output_path

Core Concepts

Conversion Pipeline

Step	Tool	Input	Output
Write	Markdown editor	Ideas	.md files
Organize	File naming	Chapters	Ordered chapters
Metadata	YAML file	Book info	metadata.yaml
Style	CSS	Design specs	style.css
Convert	Pandoc	All above	.epub / .pdf
Validate	EPUBCheck	.epub	Validation report
Publish	Distribution	Final file	Bookstores

EPUB Styling

Copy
/* epub-style.css */
body {
  font-family: Georgia, 'Times New Roman', serif;
  font-size: 1em;
  line-height: 1.6;
  margin: 1em;
  color: #333;
}

h1 {
  font-size: 2em;
  page-break-before: always;
  margin-top: 2em;
  color: #1a1a1a;
}

h2 {
  font-size: 1.5em;
  margin-top: 1.5em;
  border-bottom: 1px solid #ddd;
  padding-bottom: 0.3em;
}

blockquote {
  border-left: 3px solid #ccc;
  padding-left: 1em;
  color: #666;
  font-style: italic;
}

code {
  font-family: 'Courier New', monospace;
  background-color: #f4f4f4;
  padding: 0.2em 0.4em;
  font-size: 0.9em;
}

pre code {
  display: block;
  padding: 1em;
  overflow-x: auto;
}

img {
  max-width: 100%;
  height: auto;
}

Configuration

Option	Description	Default
output_format	Target format: epub, pdf, html, docx	"epub"
toc_depth	Table of contents heading depth	2
chapter_level	Heading level for chapter breaks	1
css_file	Path to EPUB stylesheet	"style.css"
cover_image	Path to cover image	null
pdf_engine	PDF rendering engine	"xelatex"
font_family	Default font for PDF output	"Georgia"
page_margins	PDF page margins	"1in"

Best Practices

1. Use consistent heading levels across all chapter files — H1 for chapter titles, H2 for sections, H3 for subsections — because Pandoc uses heading levels to determine chapter breaks and TOC structure
2. Create a metadata YAML file with all book information (title, author, description, language, rights) rather than passing metadata as command-line flags, for maintainability and reproducibility
3. Test EPUB output with EPUBCheck before distribution to catch validation errors that would cause rejection from ebook stores — many stores require valid EPUB 3.0 compliance
4. Use relative image paths in Markdown source and ensure all images are in a consistent directory that Pandoc can find during conversion
5. Keep chapters in separate files named with numeric prefixes (01-introduction.md, 02-getting-started.md) so they sort correctly and can be processed independently or reorganized easily

Common Issues

Table of contents not generating: Pandoc needs the --toc flag explicitly, and headings must use ATX style (# Heading) rather than Setext style (underlined) for reliable TOC generation. Also ensure --toc-depth matches the heading levels you want included.

Images not appearing in EPUB: Pandoc embeds images relative to the working directory, not the Markdown file location. Run Pandoc from the directory containing your images, or use absolute paths. For EPUB, images must be in supported formats (JPEG, PNG, SVG).

PDF rendering failing with special characters: The default PDF engine (pdflatex) cannot handle Unicode characters. Switch to XeLaTeX (--pdf-engine=xelatex) which supports full Unicode, or install the required LaTeX packages for your character set.