Pandoc for ebooks: convert anything to EPUB with one command

If you write in Markdown and want a clean EPUB without touching Calibre or Sigil, Pandoc is the tool you didn’t know you needed. It’s a command-line document converter that handles more formats than anything else out there — and it produces surprisingly good ebooks.

What Pandoc does

Pandoc converts documents between formats. Markdown to EPUB. Word to Markdown. HTML to PDF. LaTeX to EPUB. The list is long — Pandoc supports over 40 input and output formats.

For ebook creators, the key conversion is Markdown → EPUB. If you write your drafts in Markdown (as many technical writers and bloggers do), Pandoc gets you from draft to e-reader with one terminal command:

pandoc manuscript.md -o book.epub --toc

That single line creates a valid EPUB with a table of contents. No GUI. No clicking around. Just a file you can sideload to a Kindle or Kobo.

What makes Pandoc genuinely powerful isn’t just the format range — it’s the design philosophy. Pandoc treats each document as an abstract syntax tree that it parses, transforms, and writes out in the target format. So when you convert Markdown to EPUB, Pandoc isn’t doing a simple text substitution. It’s parsing your Markdown into a structured document model, understanding which pieces are headings, paragraphs, lists, and blockquotes, then writing that structure into a standards-compliant EPUB. The result is clean, semantic HTML inside the EPUB — no wrapper divs, no inline style cruft, no conversion artifacts. That’s why Pandoc output is easier to edit later and less likely to trigger validation errors.

Why use Pandoc over Calibre for conversion

Calibre is a full library manager. Pandoc is a converter. The difference matters:

Pandoc is faster. Converting a 300-page Markdown manuscript takes about 2 seconds. Calibre’s conversion pipeline is heavier because it does more — metadata management, cover embedding, format optimization.

Pandoc is scriptable. You can build automated workflows. Write a chapter in Obsidian, run a shell script, and your EPUB is ready. This is invaluable if you publish regularly or maintain documentation.

Pandoc produces cleaner output. The HTML inside Pandoc-generated EPUBs is minimal and predictable. Calibre’s output is functional but can include wrapper divs and inline styles that make later editing harder.

Calibre is better at library management. If you need to organize thousands of books, download metadata, or manage a device sync pipeline, Calibre is the right tool. Pandoc doesn’t do any of that. It converts documents and gets out of your way.

The two tools aren’t mutually exclusive. A common workflow is: draft in Markdown, convert to EPUB with Pandoc, then import into Calibre for library organization and metadata enrichment. Each tool handles the part it’s best at.

Getting set up

Install Pandoc from pandoc.org. On macOS:

macOS

brew install pandoc

Windows

winget install JohnMacFarlane.Pandoc

Linux

sudo apt install pandoc

For EPUB output, Pandoc doesn’t need any additional dependencies — it generates EPUBs natively. For PDF output via LaTeX, you’ll need a TeX distribution like TeX Live or MiKTeX installed separately.

Supported Formats

Pandoc’s full format list is broader than what’s shown here. It can read and write mediawiki, textile, reStructuredText, AsciiDoc, Org-mode, and dozens of other markup formats. For ebook creators, the practical takeaways are: you can start from Markdown, Word, HTML, LaTeX, plain text, or even an existing EPUB, and output to any major ebook format. If you have a manuscript trapped in an obscure format, Pandoc can probably read it.

A step-by-step Markdown-to-EPUB workflow

Here’s a complete workflow that takes you from Markdown files to a polished EPUB:

Step 1: Organize your chapters. Create one Markdown file per chapter. Name them with numeric prefixes so they sort correctly: 01-introduction.md, 02-the-beginning.md, 03-deepening-crisis.md, and so on.

Step 2: Add metadata. Create a metadata.yaml file with your book’s metadata:

---
title: My Novel
author: Jane Doe
lang: en-US
cover-image: cover.jpg
---

Step 3: Concatenate and convert. Use a single command that combines all chapters and applies metadata:

pandoc 01-*.md 02-*.md 03-*.md metadata.yaml -o my-novel.epub --toc --toc-depth=2

The --toc flag generates the table of contents from your headings. --toc-depth=2 limits the TOC to two heading levels, which keeps it clean. If your chapters use # for chapter titles, those become top-level TOC entries.

Step 4: Add a CSS stylesheet for custom styling:

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

A minimal stylesheet might look like:

body { font-family: serif; line-height: 1.6; }
h1 { text-align: center; margin-top: 2em; }
p { text-indent: 1.5em; margin: 0; }

Pandoc embeds the stylesheet into the EPUB automatically. Any valid CSS works — you can control fonts, margins, text alignment, drop caps, and more.

Step 5: Verify the output. Open the EPUB in Kindle Previewer or Calibre’s viewer to check formatting. Because Pandoc generates clean HTML, issues are rare, but always verify before publishing.

Batch conversion

One of Pandoc’s strongest features for publishers is batch conversion. If you have a folder of Word documents, you can convert them all to EPUB in one command:

for file in *.docx; do
  pandoc "$file" -o "${file%.docx}.epub"
done

This loops through every .docx file in the current directory, runs Pandoc on each, and saves the output with an .epub extension. For a folder with 20 chapters, that’s 20 EPUBs generated in under 10 seconds. You can also combine this with the concatenation approach: convert each chapter individually, then merge them:

pandoc chapter-*.epub -o complete-book.epub

This kind of scriptability is what sets Pandoc apart from GUI tools. Once you’ve written the commands once, you can repeat the entire build process with a single keystroke.

Custom templates

Pandoc uses templates to control the structure of output documents. The default EPUB template is good, but you might want to customize the title page, add a copyright notice, or include boilerplate front matter. To see the default template:

pandoc -D epub

Copy that output into a file, make your edits, then reference it during conversion:

pandoc manuscript.md -o book.epub --template=my-template.html

Common customizations include adding a dedication page, modifying the title page layout, or embedding custom fonts. The template system gives you full control over the EPUB’s internal structure without needing to edit the generated files by hand.

Advanced options: filters and Lua scripts

Pandoc supports filters — small programs that transform the document’s internal AST before it’s written to the output format. Filters can be written in Lua (built-in), Python, or Haskell. For ebook creators, Lua filters are the easiest to get started with:

-- capitalize-headings.lua
function Header(el)
  return pandoc.Header(el.level, pandoc.Str(pandoc.utils.stringify(el.content):upper()))
end

Save this as capitalize-headings.lua and apply it:

pandoc manuscript.md -o book.epub --lua-filter=capitalize-headings.lua

This converts every heading to uppercase. More practical filters could:

• Automatically number chapters
• Convert straight quotes to curly quotes
• Insert page breaks before every H1
• Strip specific HTML tags
• Add a “Chapter N” prefix before each heading

The filter system is what makes Pandoc extensible beyond simple conversion. If there’s a repetitive formatting task you do on every book, you can encode it as a filter and never do it manually again.

A realistic workflow

Here’s how I use Pandoc in practice:

1. Write the manuscript in Markdown, one .md file per chapter
2. Concatenate all chapters into a single file (or use Pandoc’s multi-file support)
3. Run Pandoc to generate the EPUB
4. Optionally polish in PageEdit for visual tweaks

Pandoc won’t replace Calibre for library management or Sigil for deep editing. But if a workflow starts in Markdown, Pandoc is the fastest path from draft to e-reader. It’s free, it’s fast, and it works everywhere.