How do I convert Markdown to EPUB with Pandoc?

Run: pandoc manuscript.md -o book.epub. For metadata, add YAML front matter at the top of your .md file with title, author, and date fields. For a table of contents, add --toc --toc-depth=2. For a cover image, add --epub-cover-image=cover.jpg. Pandoc produces a valid EPUB 3 file by default.

Can Pandoc convert a PDF to EPUB?

Pandoc can extract text from PDFs but does not understand page layout. For simple text-only PDFs it may work, but multi-column layouts, academic papers, and scanned PDFs produce garbled output. For reliable PDF-to-EPUB conversion with layout analysis and OCR support, use toolkit.bot or Calibre instead.

How do I add a table of contents to a Pandoc EPUB?

Use the --toc flag: pandoc manuscript.md --toc --toc-depth=2 -o book.epub. The depth controls how many heading levels appear (1 = H1 only, 2 = H1 and H2, etc.). Pandoc generates both NCX (EPUB 2) and NAV (EPUB 3) documents automatically, which satisfies KDP, Kobo, and Apple Books requirements.

What formats can Pandoc convert to EPUB?

Pandoc can convert to EPUB from: Markdown (.md), HTML (.html), DOCX (.docx), ODT, reStructuredText (.rst), LaTeX (.tex), Org-mode (.org), OPML, and more. It cannot reliably convert complex PDFs — use toolkit.bot for that. Install Pandoc with 'brew install pandoc' (macOS), 'apt install pandoc' (Linux), or download from pandoc.org.

Pandoc EPUB — Convert Markdown, HTML, and DOCX to EPUB from the Command Line

Pandoc is the most powerful free tool for converting documents to EPUB. It handles Markdown, HTML, DOCX, RST, LaTeX, and more. Here's the complete guide with commands, metadata, and CSS styling.

Install Pandoc

Pandoc is available for macOS, Windows, and Linux:

# macOS (Homebrew)
brew install pandoc

# Ubuntu / Debian
sudo apt install pandoc

# Windows (winget)
winget install JohnMacFarlane.Pandoc

Verify with pandoc --version. Pandoc 3.x is recommended; older versions have EPUB 3 limitations.

Basic EPUB Conversion

Convert a Markdown file to EPUB:

pandoc manuscript.md -o book.epub

Convert an HTML file to EPUB:

pandoc chapter.html -o book.epub --standalone

Convert a Word document (DOCX) to EPUB:

pandoc document.docx -o book.epub

Pandoc auto-detects the input format from the file extension. Use -f to specify explicitly (e.g., -f markdown).

EPUB Metadata with YAML Front Matter

Add metadata to your Markdown file using YAML front matter at the top:

---
title: "My Book Title"
author: "Author Name"
date: "2026"
lang: en
description: "A description of the book for EPUB metadata."
cover-image: cover.jpg
---

# Chapter One
...

Or pass a separate metadata file:

pandoc manuscript.md --metadata-file=meta.yaml -o book.epub

Multi-Chapter EPUBs

For books with multiple Markdown chapter files, list them in order:

pandoc ch01.md ch02.md ch03.md -o book.epub

Pandoc creates a chapter break at each H1 heading by default. Use --epub-chapter-level=2 to split at H2:

pandoc manuscript.md --epub-chapter-level=2 -o book.epub

Adding a Cover Image

pandoc manuscript.md --epub-cover-image=cover.jpg -o book.epub

The cover image must be JPEG or PNG. For KDP submission, 2,560 × 1,600 pixels minimum, 300 DPI recommended.

Custom CSS Styling

Create a styles.css file and reference it:

pandoc manuscript.md --css=styles.css -o book.epub

Sample minimal CSS for readable ebooks:

body {
  font-family: Georgia, serif;
  font-size: 1em;
  line-height: 1.6;
  margin: 1em;
}
h1, h2 { font-family: sans-serif; }
p { text-indent: 1.2em; margin: 0; }
p:first-child, h1 + p, h2 + p { text-indent: 0; }

Generating a Table of Contents

Add a TOC automatically:

pandoc manuscript.md --toc --toc-depth=2 -o book.epub

--toc-depth=2 includes H1 and H2 headings in the TOC. Pandoc generates both NCX (EPUB 2 compatibility) and NAV (EPUB 3) documents.

Pandoc EPUB Limitations

Input must be text-based: Pandoc cannot convert scanned PDFs or image-only PDFs — use a tool with OCR for those.
No PDF input (for non-text PDFs): Pandoc reads PDF as text extraction only. Multi-column or complex layouts in PDF produce garbled output. Use toolkit.bot for PDF-to-EPUB with layout analysis.
No GUI: Pandoc is command-line only. For non-technical users, Calibre's GUI is easier.
MathML support: Pandoc converts LaTeX math to MathML in EPUB, but not all EPUB readers render MathML.

Validating Pandoc EPUB Output

Run EPUBCheck on the output to verify the EPUB passes spec:

java -jar epubcheck.jar book.epub

Pandoc 3.x produces EPUB 3 by default, which passes EPUBCheck. For EPUB 2 compatibility (older readers), add --epub-version=2.

Have a PDF (not Markdown) to convert? toolkit.bot handles layout analysis, heading detection, and OCR.

Convert PDF to EPUB →