Markdown to EPUB is the publishing pipeline indie authors use when they want their book to look like a book and ship before the next rewrite. Plain-text chapters, one conversion command, an EPUB validates, and KDP accepts the upload. No InDesign, no Word manuscript template, no formatter on Fiverr.
TL;DR
- Yes, you can publish a real book from markdown. KDP, Apple Books, Kobo, and Google Play Books all accept EPUB; markdown is the cleanest way to get there.
- The standard stack: Pandoc converts, Calibre polishes, EPUBCheck validates, KDP / Apple Books / Kobo distribute.
- One file per chapter,numbered. The folder is your manuscript’s spine.
- Metadata is non-negotiable.Title, author, language, identifier, cover. Stores accept without; readers don’t find you without.
- Want a print edition too? The same markdown exports to a designed PDF via mdclaudy’s manuscript template.
The state of markdown → EPUB in 2026
EPUB is the open standard for ebooks. It’s a zip file containing XHTML, CSS, images, and a manifest. Reading apps — Apple Books, Kindle (via conversion), Kobo, Adobe Digital Editions, every browser-based reader — understand it. The current spec is EPUB 3.3, published by the W3C in 2023.
Three tools matter for the markdown-to-EPUB route:
- Pandoc — the universal document converter, free, command-line. Maintained by John MacFarlane since 2006. The reference tool for markdown to almost any format.
- Calibre — the open-source ebook library manager with built-in conversion, cover designer, and metadata editor. GUI-friendly. Indispensable for the polishing phase.
- mdclaudy — the editor and conversion path described in this post. Designed templates for the print PDF counterpart; clean EPUB output for the digital one.
Online generic converters exist — Vertopal, Zamzar, CloudConvert— and they will technically produce an EPUB from a markdown file. They don’t handle chapter structure, metadata, or covers. They produce a single-chapter ebook with a generic title. Useful for a one-off test; not the right tool for a book you’re selling.
The folder structure of a book
Before writing a line, set up the file system. Books that ship cleanly almost always look like this:
my-novel/
├── meta.yml
├── cover.jpg
├── chapters/
│ ├── 00-title-page.md
│ ├── 01-copyright.md
│ ├── 02-dedication.md
│ ├── 03-prologue.md
│ ├── 04-chapter-one.md
│ ├── 05-chapter-two.md
│ ├── ...
│ ├── 30-epilogue.md
│ ├── 31-acknowledgments.md
│ └── 32-about-the-author.md
└── images/
└── map.pngNumbering is for sort order — Pandoc concatenates in alphabetical order when you pass *.md. Leave gaps (10, 20, 30) so you can drop a chapter in later without renumbering. mdclaudy uses a collection with drag-to-reorder instead, but the underlying principle is the same: one chapter, one file, the order is the book.
EPUB metadata — the fields that matter
EPUB metadata lives in the content.opf manifest. With Pandoc, you write it in YAML and pass --metadata-file=meta.yml. The minimum viable file:
--- title: The Quiet Garden author: Mohammed Agrat language: en identifier: scheme: ISBN text: 978-1-234567-89-0 date: 2026-05-26 publisher: Independent rights: © 2026 Mohammed Agrat. All rights reserved. description: | A novel about a botanist who inherits a house with a garden that refuses to grow anything she plants. subject: - Fiction - Literary fiction - Magical realism cover-image: cover.jpg ---
Two metadata details that actually move sales:
- Subject tagsmap to BISAC categories on Amazon and BIC categories on European stores. They drive which-bestseller-list-you-appear-on. Pick the most-specific subcategory you legitimately fit — “Literary fiction” beats “Fiction”, “Coming of age” beats “Literary fiction”.
- Description is your back-cover blurb. Stores display it verbatim. 150–200 words; first sentence does the lifting.
The cover image
Specs the major stores agree on:
- Dimensions: 1600 × 2400 pixels (2:3 aspect), minimum. KDP recommends 2560 × 1600 minimum on the long edge.
- Format: JPG or PNG. JPG for photo-based covers, PNG for graphic covers with sharp lines.
- File size: under 50MB. Most covers come in under 2MB.
- RGB, not CMYK. CMYK will render wrong in reading apps.
- Title and author must be legible at thumbnail size (160×240 on a phone). This is the most-violated rule in indie publishing.
Tools: Canva, Affinity Publisher, Adobe InDesign, or a designer on Reedsy($200–800 for a cover that won’t look like a self-published cover). The cover is the only piece of design that genuinely matters for sales; spend on it.
The conversion command
Pandoc’s entire markdown-to-EPUB command, fully loaded:
pandoc \ --from gfm \ --to epub3 \ --metadata-file=meta.yml \ --epub-cover-image=cover.jpg \ --toc \ --toc-depth=2 \ --epub-chapter-level=1 \ --css=epub.css \ --output=quiet-garden.epub \ chapters/*.md
Two flags worth understanding:
- --epub-chapter-level=1: every
# heading(H1) becomes a new chapter file inside the EPUB. Use H1 only for chapter titles; use H2 for in-chapter section breaks. - --toc --toc-depth=2: generates a clickable table of contents at depth 2 (chapters + first-level sections). Most readers want this.
The optional epub.css file lets you control typography inside the EPUB — line height, font choice for body and headings, chapter heading style. Reading apps will override font choices if the reader has theirs set, but spacing and structural CSS sticks.
The mdclaudy export path
mdclaudy ships EPUB export from any collection. The flow:
- Create a collection. Drag your chapter documents in. Reorder.
- Open the collection’s export panel. Pick EPUB.
- Fill in metadata (title, author, ISBN, description, subject tags). Upload a cover image.
- Export. mdclaudy runs the conversion server-side with Pandoc under the hood, validates with EPUBCheck, and hands you a finished EPUB.
The point of doing this in mdclaudy instead of by hand: the same collection also exports to a designed PDF for the print edition. The markdown stays the source of truth; the EPUB and the print PDF are two renders of the same document.
Validation: run EPUBCheck before you upload
EPUBCheck is the W3C’s reference validator. Every store runs their own version on upload; failing validation means rejection. Save the round trip by running it locally:
# install brew install epubcheck # Mac npm install -g epubcheck # cross-platform via Node # run epubcheck quiet-garden.epub
Pandoc-generated EPUBs almost always pass. The common failure modes when they don’t: missing alt text on cover image, an image reference that doesn’t exist on disk, a malformed YAML metadata field. Read the error, fix the source, re-run.
Upload: where to put your finished EPUB
Three strategies for distribution:
- Amazon KDP exclusive— enroll in Kindle Unlimited, collect “page reads” revenue, accept 90 days of Amazon exclusivity. Worthwhile if you write in genres where KU readers live (romance, thriller, fantasy). Less compelling for literary fiction.
- Wide distribution, direct uploads— KDP, Apple Books, Kobo, Google Play Books, Barnes & Noble Press. Five uploads, five dashboards, five royalty rates. Maximum control, most admin.
- Aggregators — Draft2Digital (free, takes ~10% royalty cut after store cut) or PublishDrive distribute one upload to every store including library systems. Simpler. Slightly lower per-sale royalty. Most indie authors run KDP direct + Draft2Digital for the rest.
Markdown is the indie author’s least romantic, most useful decision. The romance lives in the prose, not in the file format.
Also want a print edition?
The print companion to a digital EPUB is a designed PDF — fixed-page layout, real typography, trim size matching your printer’s spec (KDP Print accepts 5x8, 5.25x8, 5.5x8.5, 6x9, and a few more).
This is the gap mdclaudy was built to fill. The same markdown chapters that produce your EPUB also export through the Manuscript template — ligatures, drop caps, page numbers, chapter openers, running heads. Upload the PDF to KDP Print or IngramSpark for a hardcover or paperback companion.
We wrote a full walkthrough in the markdown to PDF guide covering trim sizes, bleed, ISBN considerations, and the Quick vs Print-Quality engine choice.
Real example: a 75,000-word novel shipping checklist
What an indie author’s ship-the-book Tuesday actually looks like:
- 9:00am — final manuscript read-through complete. 75,000 words across 28 chapter
.mdfiles in a folder. - 9:30 — write
meta.ymlwith title, author, ISBN (purchased separately from Bowker), description, subject tags. 15 minutes. - 9:45 — finalize cover image (already designed weeks ago). Drop into project root as
cover.jpg. - 10:00 — run Pandoc. EPUB generated in 4 seconds.
- 10:01 — EPUBCheck. Clean.
- 10:05 — sideload to Apple Books and Kindle Previewer. Read the first chapter on each. Catch one footnote that lost a period. Fix the source, re-run.
- 10:30— generate the print PDF via mdclaudy’s Manuscript template. Quick proof read.
- 11:00 — upload EPUB to KDP. 24-hour review window.
- 11:15— upload EPUB to Draft2Digital. Configures Apple Books, Kobo, Google Play, B&N in one form.
- 11:45 — upload print PDF + cover wrap to KDP Print. 72-hour review window.
- 12:00 — lunch. Book ships in 1–3 days.
Frequently asked questions
The honest summary
Markdown to EPUB is the indie publishing pipeline you wish someone had described to you ten years ago. The conversion is one command. The validator is free. The stores accept it. The format costs nothing. The only friction is writing the book.
And the print companion — the trim-sized PDF that goes to a KDP Print or IngramSpark order — is the same markdown, exported through a template designed by someone who cared. That’s what we built mdclaudy for. Write once, ship in three formats.