Understanding Markdown → EPUB
Author in Markdown, ship as an ebook.
Why writers prefer Markdown, what Pandoc does to make EPUB, and the metadata/cover rituals that turn a doc into a book.
Markdown is the authoring medium.
Writers want to focus on prose; Markdown gives them headings, lists, links, and emphasis with minimal punctuation. The output is plain text that survives every tool — git, email, paste-into-anywhere. The downside: no native chapter structure, no metadata, no cover image. EPUB needs all of those. The conversion adds the structure; the Markdown stays editable.
Pandoc is the answer.
John MacFarlane's universal document converter. pandoc book.md -o book.epub --metadata-file=metadata.yaml --epub-cover-image=cover.jpg produces a valid EPUB. Pandoc handles: H1 → chapter file split (or H2, configurable), TOC generation from headings, image embedding, footnote conversion, code-block syntax highlighting, internal cross-references. The 90 % case is one command.
The metadata file.
A YAML sidecar with the book's identity: title, creator(author), publisher, language, date,rights, description, subject (BISAC categories). Some stores require identifier (ISBN or UUID). The metadata becomes the OPF's dc:* elements, which the store's catalogue reads. Skip the metadata and the book is "Untitled" on every reader.
The cover image.
Every store demands one. Specs differ: Amazon wants ≥1.6 MP JPEG at 1600 × 2560, Apple wants ≥1400 × 1873, Kobo accepts smaller. Safe target: 1600 × 2560 JPEG. Pandoc's --epub-cover-image embeds it; the EPUB's OPF references it as the cover-image property. Without a cover, half the storefronts mark the book as low quality and bury it.
A worked book.
50,000-word novel as book.md with 30 chapter H1s, plus metadata.yaml, cover.jpg, and inline images. Pandoc command: ~5 seconds. Output: a valid EPUB 3 with auto-generated TOC, 30 chapter files, embedded fonts (optional), styled with a provided CSS file. Pass through epubcheck → 0 errors. Submit to KDP, Kobo, Apple Books. Three storefronts in under 30 minutes of human time.
50k-word novel
md + yaml + jpg → EPUB
One pandoc command, validate, ship.
pandoc book.md --metadata-file=metadata.yaml --epub-cover-image=cover.jpg
= 3 stores in 30 minutes
Where it falls down.
Heavy typography (drop caps, complex layouts) — Markdown can't express it, the EPUB comes out plain. Fixed-layout books (children's books, art books, comics) — EPUB supports them but Pandoc doesn't produce them. Right-to-left languages — works but needs extra metadata. Heavily-footnoted academic prose — Pandoc handles footnotes, but the cross-link rendering depends on the reader. For most fiction and most non-fiction, Markdown → EPUB is the lowest-friction publishing pipeline.