Convert2EPUB
Menu
← Blog

How to convert Markdown to EPUB: Pandoc, or a no-install converter

Last updated: 11 November 2026

The quickest way to convert Markdown to EPUB is Pandoc: run pandoc book.md -o book.epub and you get a valid EPUB. If you don't want to install anything, upload the .md file to a web converter such as Convert2EPUB. Either way, the quality of the ebook depends mostly on how you structure your headings and metadata before converting.

What do you need to convert a Markdown file to EPUB?

You need a Markdown file with a clear heading structure, a title and author, and a tool that writes EPUB. Pandoc is the standard command-line tool. A browser converter does the same job without an install.

Before converting, make sure the source is ready:

  • One # heading per chapter. Pandoc splits an EPUB into chapters at level-1 headings by default, according to the Pandoc User's Guide. If you write chapters as ##, change that or set the split level (covered below).
  • Title and author in a metadata block at the top of the file, not just in a heading.
  • Images with relative paths that resolve from where you run the command, plus alt text.
  • No raw HTML you can't live without. Simple tags usually survive, but scripts, iframes and CSS tricks don't belong in an e-reader file.

How do I convert Markdown to EPUB with Pandoc?

Install Pandoc, put a YAML metadata block at the top of your file, and run one command. Pandoc builds the table of contents from your headings.

1. Add metadata

Pandoc reads EPUB metadata from a YAML block in the Markdown file, or from a separate YAML file, as the Pandoc manual describes. A minimal block:

---
          title: The Lighthouse Letters
          author: Dana Whitfield
          lang: en-GB
          date: 2026-11-11
          cover-image: cover.jpg
          ---

lang matters more than people expect. It controls hyphenation and text-to-speech on some readers. The date is your own choice, so use the publication date you want shown.

2. Run the command

pandoc book.md -o book.epub --toc --toc-depth=2
  • --toc-depth sets how many heading levels appear in the contents. According to the Pandoc manual, the default is 3, so levels 1, 2 and 3 are listed. For a novel, 1 or 2 is usually cleaner.
  • --epub-cover-image=cover.jpg does the same job as the cover-image field. Pandoc recommends a cover under 1000px in width and height.
  • --epub-title-page=false removes the generated title page if you've written your own.

3. Combine several files

Many writers keep one file per chapter. Pass them in order and Pandoc joins them:

pandoc 01-intro.md 02-first-night.md 03-storm.md -o book.epub

Name files with leading numbers so shell ordering matches reading order. Put the metadata block in the first file only.

4. Style it, lightly

Pandoc applies a default stylesheet. To change it, pass --css=epub.css. Keep the CSS minimal: set paragraph indentation and heading margins, and leave font family and size alone. Readers let people choose both, and overriding them removes that control.

How should I structure headings so the chapters and table of contents come out right?

Use # for chapters and ## for sections inside them, and don't skip levels. The EPUB's navigation menu is generated from these headings, so the structure you write is the structure the reader gets.

Your MarkdownWhat happens in the EPUB (Pandoc defaults)
# ChapterStarts a new chapter file and appears in the contents
## SectionAppears in the contents (depth 3 by default) but stays inside the chapter file
### SubsectionAppears in the contents only if depth allows
Bold text styled as a headingNot a heading; won't appear in the contents

Two common problems:

  • A book with only one # heading. The whole book becomes a single large file. The Pandoc manual notes that this option only affects the internal composition of the EPUB, not how chapters appear to readers, and that some readers can be slow with very large chapter files. For a long document with few top-level headings, use --split-level=2 or 3.
  • A title written as # plus chapters also as #. The title then shows up as a chapter. Put the title in the YAML block and keep # for real chapters.

If your contents page still looks wrong afterwards, our guide to fixing a missing or broken EPUB table of contents walks through the checks.

Is there a way to convert Markdown to EPUB without installing Pandoc?

Yes. A web converter that accepts .md files lets you upload, set the title and author, and download the EPUB. It suits one-off conversions and anyone who doesn't want a command line.

Here is how the two approaches compare:

PandocBrowser converter
Install neededYesNo
Repeatable in a build script or CIYesNo
Custom CSS, fonts, filtersFull controlLimited to the tool's settings
Multiple files mergedYes, by listing themCombine into one file first
Best forBooks you rebuild oftenQuick, occasional conversions

Convert2EPUB's upload box lists Markdown among the accepted formats, with a limit of 100 MB. It has settings for title, author, reflowable or fixed layout, and target device. Its free Standard model is described on the site as good for simple layouts like novels, which is also what most Markdown manuscripts are. If you're unsure whether reflowable is the right choice, see our comparison of reflowable vs fixed-layout EPUB. For prose, it is.

What should I check before sending the EPUB to a reader?

Open the file in at least one real reader app and run through a short checklist. Most Markdown-to-EPUB problems are visible in the first five minutes.

  • Contents: open the navigation menu. Every chapter should be there, in order, with sensible names.
  • Cover and title: the cover should show in your library view, and the title and author should read correctly.
  • Images: check that each image appears, scales to the screen and has no stray border.
  • Code blocks and tables: long lines in code blocks can run off the screen on small readers. Wrap them or shorten them. Wide tables are better rewritten as lists for a 6-inch screen.
  • Footnotes: Pandoc turns Markdown footnotes into linked notes. Tap one and make sure it takes you back.
  • Validation: if you plan to publish through a store, run the file through EPUBCheck, the W3C-backed validator that stores commonly use. It catches problems that readers silently forgive.

For small e-ink screens, our article on EPUB settings for a 6-inch e-ink reader covers what to set in the file and what to set on the device.

If you'd rather skip the setup, you can upload your .md file to Convert2EPUB and download a reflowable EPUB.

Can I read a Markdown-made EPUB on a Kindle?

Yes. Send the EPUB to your Kindle by email or through the Send to Kindle app, and you don't need to convert it to MOBI or AZW3. Convert2EPUB's own page says Send to Kindle takes an EPUB as it is. Our guide to sending an EPUB to your Kindle has the steps.

Frequently asked questions

Can Pandoc convert Markdown straight to MOBI or AZW3?

No. Pandoc writes EPUB, not MOBI or AZW3. Current Kindle workflows accept EPUB directly, so a separate conversion is usually unnecessary. Only very old Kindles need MOBI.

Why is my EPUB one giant chapter?

Pandoc splits chapters at level-1 headings by default. If your Markdown has one # or none, everything lands in one file. Change your chapter headings to #, or set --split-level=2.

How do I add a cover image?

Add cover-image: cover.jpg to the YAML block, or pass --epub-cover-image=cover.jpg. The Pandoc manual recommends an image under 1000px in width and height. Keep the path relative to where you run the command.

Does Markdown formatting like bold, lists and block quotes survive?

Yes. Standard Markdown elements become their HTML equivalents inside the EPUB, and the reader's own styling displays them. Extensions vary by tool, so check unusual syntax such as definition lists or task lists in the output.

Can I convert a whole folder of Markdown files?

With Pandoc, yes. List the files in order or use a glob such as *.md, as a DEV Community walkthrough does with a documentation repository. Number your filenames so the order is predictable.

Ready to convert your own PDF? It's free for ordinary text documents, no account required.

Convert a PDF to EPUB →