Guide

How to Convert Markdown to EPUB (and When to Use PDF Instead)

July 5, 2026 · 4 min read

Writing a book, a manual, or a long guide in Markdown is a smart move — plain text, versionable, no proprietary editor. When it's time to ship, you have two good targets: EPUB for a reflowable ebook that adapts to any screen and e-reader, or PDF for a fixed, print-ready document that looks identical everywhere. This guide shows how to build an EPUB from Markdown with Pandoc, and helps you decide which format your readers actually want.

The tool for the job: Pandoc

Pandoc is the standard way to turn Markdown into EPUB. The simplest possible command:

pandoc book.md -o book.epub

That already produces a valid EPUB. The rest of this guide is about making it a good one — with a title, an author, a cover, and proper chapters.

Add metadata

E-readers and stores read the book's title, author, and language from its metadata. The cleanest way is a small YAML block at the top of your Markdown, or a separate metadata file:

---
title: The Markdown Handbook
author: Jordan Rivera
language: en-US
date: 2026
rights: © 2026 Jordan Rivera
---

With that block at the top of book.md, Pandoc picks it up automatically. Alternatively, pass a metadata file: pandoc book.md --metadata-file meta.yaml -o book.epub.

Add a cover and a table of contents

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

• --epub-cover-image sets the cover shown in the library and store.
• --toc generates a navigable table of contents; --toc-depth=2 includes chapters and sections.

Control where chapters split

Pandoc breaks the EPUB into chapter files at a heading level you choose. By default it's the top level; set it explicitly with:

pandoc book.md --toc --epub-chapter-level=1 -o book.epub

That makes every # (H1) a new chapter. If your book uses # for the title and ## for chapters, use --epub-chapter-level=2 instead. Clean chapter splitting is what makes navigation and progress tracking work properly on e-readers.

Embed fonts and styling (optional)

For a custom look, pass a stylesheet and embed fonts so the book renders the same on every device:

pandoc book.md --css epub.css --embed-font=MyFont.ttf -o book.epub

Keep EPUB CSS simple — e-readers support a subset of CSS, and readers can override fonts and sizes anyway (that's the point of a reflowable format).

EPUB or PDF? Pick by how it's read

This is the decision that matters most, so choose deliberately:

Choose EPUB for a novel, a long-form guide, or anything read on an e-reader where readers want to control font size. Choose PDF for a manual, a report, a worksheet, a résumé, or anything with tables, code, or precise layout that must look the same for everyone — and anything meant to be printed.

If PDF is the better fit

For a fixed-layout document, you don't need Pandoc or LaTeX at all. Paste your Markdown into a browser converter like ConvertMDapp, preview it live, and click Export PDF. You get selectable text, clean page breaks, and a small file — entirely in your browser, with nothing uploaded. It's the fastest route when your "ebook" is really a report or handbook people will read on a laptop or print.

For the full picture on the PDF side, see the guide to converting Markdown to PDF and Markdown to Word vs PDF.

FAQ

What's the easiest way to convert Markdown to EPUB? Install Pandoc and run pandoc book.md -o book.epub. Add --toc, --epub-cover-image, and a YAML metadata block for a polished result.

Should I publish my Markdown as EPUB or PDF? EPUB for reflowable reading on e-readers and phones; PDF for fixed-layout documents with tables, code, or print needs. Many authors ship both — an EPUB from Pandoc and a PDF from a browser converter.

How do I add chapters to my EPUB? Use heading levels as chapter boundaries and tell Pandoc which level to split on with --epub-chapter-level=1 (or =2 if # is your book title). Add --toc for navigation.