Three methods compared — and how to make the result actually work on Kindle
To convert markdown to EPUB, you have three practical options: run pandoc book.md -o book.epub on the command line, drop your .md file into a hosted converter and download the result, or paste it into a generic online converter. All three produce a valid EPUB. The difference — and the reason most converted files look wrong on a Kindle — is everything that happens after the file validates: the table of contents, scene breaks, fonts, and chapter styling. This guide covers all three methods and the Kindle-specific pitfalls each one leaves behind.
I build EbookFormatter's EPUB generator by hand — it assembles the EPUB archive byte by byte rather than leaning on a library — so this guide is written from the inside of the format, not from the outside looking at a converter's "Convert" button.
An EPUB is not a single document. It's a ZIP archive with a specific internal structure, renamed with an .epub extension. If you rename a valid EPUB to .zip and unzip it, you'll find roughly this:
mybook.epub
├── mimetype (declares "application/epub+zip")
├── META-INF/
│ └── container.xml (points to the package file)
└── OEBPS/
├── content.opf (metadata, manifest, reading order)
├── nav.xhtml (the navigable table of contents)
├── chapter-1.xhtml (your chapters, as XHTML)
├── chapter-2.xhtml
└── styles.css (typography)Your markdown becomes the .xhtml chapter files. The content.opf lists every file and defines the reading order. The nav.xhtml is the table of contents that lets a reader jump between chapters. Knowing this matters: most "my EPUB looks broken" problems are a missing or malformed nav.xhtml, or chapters that didn't get split into separate XHTML files. EPUB comes in two versions — EPUB 2 (older, NCX-based navigation) and EPUB 3 (current, XHTML5 + nav.xhtml). Produce EPUB 3 unless you have a specific reason not to.
Each method makes a valid file. They differ in how much setup they need and how much book-quality typography you get for free.
| Method | Setup | Typography & TOC | Best for |
|---|---|---|---|
| Pandoc (CLI) | Install required; comfortable with a terminal | Plain by default; full control if you write your own CSS | Developers who want a scriptable, repeatable build |
| Generic online converter | None | Minimal — bare defaults, no book styling | A quick one-off when appearance doesn't matter |
| Hosted markdown-to-book tool | None | Curated themes, drop caps, scene breaks, navigable TOC built in | Authors who want a Kindle-ready book without writing CSS |
Pandoc is the reference tool for document conversion and it does markdown-to-EPUB well. The minimal command is:
pandoc book.md -o book.epubFor a real book, add metadata as a YAML block at the top of your markdown and split the build across chapter files:
---
title: My Novel
author: Jane Author
language: en-US
---
pandoc -o book.epub --toc --css=styles.css \
--epub-cover-image=cover.jpg \
ch1.md ch2.md ch3.mdPandoc defaults to EPUB 3 (use -t epub2 if you need the older version), embeds local images automatically, builds the table of contents from your headings with --toc, and applies your stylesheet with --css. The catch: the default styling is deliberately minimal. Drop caps, centered scene breaks, chapter ornaments, and font pairing are all on you — you'll be writing and debugging CSS to get a result that looks like a published book.
Paste-and-download converters turn a .md file into an EPUB in one step with zero setup. They're fine for a throwaway file. For a book you intend to sell, they fall short in predictable ways: no real chapter splitting (the whole book lands on one scroll), no styled scene breaks, no front-matter handling, and a table of contents that's either absent or flat. You also hand your manuscript to a third-party server you don't control.
EbookFormatter sits between the two: no install like an online converter, but book-aware like a hand-tuned Pandoc build. You structure your markdown manuscript with chapter headings and page-type annotations, pick a typography theme, and download a Kindle-ready EPUB 3. Chapters split on # headings, scene breaks render as styled centered separators, and the navigable table of contents is generated for you. The file is built byte by byte on the server and never stored with a third party. Convert your markdown to EPUB in a few seconds — no account.
A file that opens fine in your desktop reader can still look wrong once it's on a Kindle, because Amazon re-renders your EPUB into its own format and enforces its own rules. These are the problems that actually generate support emails:
Since March 18, 2025, Amazon KDP no longer accepts MOBI files. KDP now ingests EPUB 2.0 and EPUB 3.0 (plus its own KPF and DOCX). If a guide tells you to convert to MOBI for Kindle, it's out of date — convert to EPUB and upload that.
If you type * * * in markdown and convert naively, it can survive as plain left-aligned text in the middle of your prose. A proper scene break is a styled, centered separator. Either use a tool that converts the marker into a centered break, or add CSS that centers that paragraph. EbookFormatter does this from a single --- in your markdown.
Kindle ebooks are reflowable, and Amazon expects a navigable table of contents so readers can jump to any chapter. KDP's own guidance is to apply Heading 1 to chapter titles so the TOC builds correctly. A file with one giant chapter and no nav.xhtml entries gives readers no way to navigate. Split on top-level headings and confirm the nav document lists every chapter.
Kindle lets readers choose their own font and size, so the fancy display font you embedded is often overridden — and over-embedding fonts can trip validation warnings. Use embedded fonts sparingly (a heading accent at most) and let the reader's body font do its job.
Because ebooks reflow, KDP states plainly that page numbers and page counts "don't apply" and that ebooks don't use headers or footers — so don't add them. Manual page numbers typed into your manuscript will show up as stray text mid-paragraph on a small screen. Strip them before converting.
An EPUB carries its own title, author, and language inside content.opf — and a separate cover image referenced in the manifest. A naive conversion often drops all of it: the file opens as "Untitled," with no author and no cover, which KDP will flag. With Pandoc, supply metadata in a YAML block and pass --epub-cover-image=cover.jpg. With a generic converter, you usually can't set any of it. A book-aware tool asks for the title, author, and an optional cover up front and writes them into the package so the file is shelf-ready. Whatever route you take, open the finished EPUB and confirm the title, author, and cover are present before uploading.
Whatever method you used, test the EPUB in Kindle Previewer 3 (Amazon's free desktop tool) before uploading. It opens .epub files and renders them the way a real Kindle will, which catches broken navigation and reflow problems your desktop reader hides.
Upload your .md file to a hosted converter and download the EPUB — no install. If you prefer the terminal, run pandoc book.md -o book.epub. Both produce a valid EPUB; the hosted route also applies book typography and a navigable TOC that bare Pandoc output skips.
Yes. Since March 18, 2025, KDP accepts EPUB 2.0 and 3.0 (MOBI is no longer accepted). A valid EPUB from any of the methods above uploads directly.
EPUB. Amazon stopped accepting MOBI uploads in March 2025 and now ingests EPUB, converting it internally. Produce EPUB, not MOBI.
Only with Pandoc or a generic converter, if you want book-quality styling. A book-aware hosted tool ships curated typography — drop caps, scene breaks, chapter styling — so you write none.
Ready to convert? Upload your markdown file and download a Kindle-ready EPUB in seconds. New to structuring a manuscript? Start with the Formatting Guide.