Creating Professional EPUB3 Ebooks from Markdown with Pandoc

In the world of self-publishing and technical documentation, Markdown has become a go-to format for writing clean, distraction-free content. Pair it with Pandoc, the Swiss Army knife of document conversion, and you have a powerful, free workflow for producing high-quality EPUB3 ebooks — the modern standard for reflowable digital books.

This guide will walk you through the entire process: from a single Markdown file to a multi-chapter book with proper metadata, custom styling, internal cross-references, a table of contents, and a cover. By the end, you'll be able to create EPUB3-compliant ebooks and validate them professionally.

Why Pandoc + Markdown for EPUB?

• Markdown is simple and portable — Write once, convert anywhere.
• Pandoc handles the heavy lifting — Automatic table of contents, cross-references, metadata embedding, and EPUB3 features like MathML.
• Fully open-source and scriptable — Perfect for automation or Git-based workflows.
• EPUB3 compliance — Pandoc produces valid EPUB3 by default in recent versions (2.0+).

Step 1: Install Pandoc

Download the latest version from the official site: pandoc.org/installing.html.

• macOS: brew install pandoc
• Ubuntu/Debian: sudo apt install pandoc
• Windows: Use the installer or Chocolatey (choco install pandoc)

Verify: pandoc --version (as of early 2026, 3.x is current).

Step 2: Basic Single-File Conversion

Start simple:

pandoc input.md -o book.epub

This produces a basic EPUB3 file. Add common enhancements:

pandoc input.md \
  -o book.epub \
  --toc \
  --toc-depth=2 \
  --epub-cover-image=cover.jpg

• --toc: Generates a navigable table of contents.
• --toc-depth=2: Includes up to level-2 headings (##).
• --epub-cover-image=cover.jpg: Embeds your cover (JPEG or PNG, ideally 1600×2560 px for good quality across readers).

Step 3: Multi-File Books (Chapters)

Split your book into logical Markdown files (e.g., chapter1.md, chapter2.md). Pandoc concatenates them in the order you specify:

pandoc title.txt chapter1.md chapter2.md chapter3.md appendix.md \
  -o mybook.epub \
  --toc --toc-depth=2 \
  --epub-cover-image=cover.jpg

• title.txt is optional — a separate file for front matter (title page, dedication, etc.).
• Order matters: List files sequentially.

Internal Cross-References Across Files

Pandoc merges all files into one document, so do not include filenames in links. Use header anchors only.

In chapter2.md:

## Advanced Features {#advanced}

In chapter1.md:

See the [advanced features section](#advanced) for details.

To ensure uniqueness:

• Use explicit IDs: ## Section Title {#my-unique-id}
• Pandoc auto-generates IDs from header text (lowercased, spaces → dashes) and resolves duplicates by appending -1, -2, etc.

Avoid --file-scope — it isolates files and breaks simple cross-references.

For chapter splitting (separate XHTML files per top-level chapter):

pandoc chapters/*.md -o book.epub --epub-chapter-level=1

Cross-references still work automatically.

Step 4: Metadata (The Professional Touch)

Metadata makes your book look polished in readers (title, author, date, description, ISBN, etc.).

Option A: Inline YAML (Simple)

Add a YAML block at the top of your first Markdown file (or title.txt):

---
title: My Awesome Book
subtitle: A Practical Guide
author: Your Name
date: 2026
lang: en-US
---

Option B: External YAML File (Recommended for Multi-File Projects)

Create metadata.yaml:

---
title:
  - type: main
    text: My Awesome Book
  - type: subtitle
    text: Mastering Pandoc for EPUB3
author:
  - Your Name
date: 2026
lang: en-US
rights: © 2026 Your Name. Creative Commons Attribution 4.0
description: A comprehensive guide to creating professional ebooks with Pandoc.
subject:
  - Markdown
  - Pandoc
  - Self-Publishing
identifier:
  - scheme: ISBN
    text: 978-1-234-56789-0
publisher: Independent
cover-image: cover.jpg
css: styles/epub.css
---

Run Pandoc with:

pandoc metadata.yaml chapter*.md \
  -o book.epub \
  --toc --toc-depth=2 \
  --epub-cover-image=cover.jpg

The structured title and author formats map cleanly to EPUB3 Dublin Core metadata.

Step 5: Custom Styling with CSS

Create a folder styles/ and a file styles/epub.css:

/* Basic typography */
body {
  font-family: Georgia, serif;
  line-height: 1.6;
  hyphens: auto;
  -webkit-hyphens: auto;
}

/* Headings */
h1, h2, h3 {
  page-break-before: avoid;
  text-align: center;
}

/* Code blocks */
pre {
  background: #f4f4f4;
  padding: 1em;
  overflow-x: auto;
}

/* Blockquotes */
blockquote {
  border-left: 4px solid #ccc;
  margin: 1.5em 0;
  padding-left: 1em;
  font-style: italic;
}

/* Custom fonts (embed if you have rights) */
@font-face {
  font-family: 'CustomSerif';
  src: url('../fonts/CustomSerif.ttf');
}
body { font-family: 'CustomSerif', Georgia, serif; }

Add to command:

--css=styles/epub.css

Note: For embedded fonts, place font files in a fonts/ directory and reference paths correctly. Some readers (Kindle) have limited font embedding support.

Step 6: EPUB3-Specific Features

Pandoc defaults to EPUB3. Force it if needed:

--to=epub3

Useful for:

• MathML (math renders natively in many readers)
• Media overlays
• Better accessibility

Step 7: Validate Your EPUB3

Never skip validation!

1. Download EPUBCheck from github.com/w3c/epubcheck (Java required).

2. Run:

java -jar epubcheck.jar mybook.epub

It will report errors/warnings. Common fixes:

• Invalid cover dimensions → resize to recommended ratio.
• Missing navigation document → ensure --toc is used.
• CSS issues → simplify or test in Calibre.

Also test in real readers:

• Calibre (free, excellent for editing/viewing)
• Apple Books
• Google Play Books
• Thorium Reader (accessibility-focused)

Final Example Command

pandoc metadata.yaml title.txt chapter*.md \
  -o mybook.epub \
  --toc --toc-depth=3 \
  --epub-cover-image=cover.jpg \
  --css=styles/epub.css \
  --to=epub3

Conclusion

With Pandoc and thoughtful Markdown structure, you can produce professional, standards-compliant EPUB3 ebooks entirely from plain text. No expensive software, no proprietary lock-in.

Start small, validate often, and iterate. Your readers — and future self — will thank you for clean, accessible books.

Happy writing! If you run into issues, the Pandoc manual and community forums are excellent resources.