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.txtis 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!
Download EPUBCheck from github.com/w3c/epubcheck (Java required).
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
--tocis 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.