Markdown and EPUB have more in common than either has with a word processor. Both describe structure — this is a heading, this is a list, this is emphasis — and leave the appearance to whatever is doing the rendering. That is why the conversion is usually clean, and why the things that break are precisely the things you added to control appearance.
What an EPUB actually is
An EPUB is a zip file with a fixed set of parts inside it. Knowing the parts is the difference between fixing a rejected upload in five minutes and reinstalling three applications.
| Inside the zip | What it is | Where it comes from |
|---|---|---|
| mimetype | One line, uncompressed, first in the archive | The exporter. Get it wrong and nothing opens the file |
| META-INF/container.xml | Points at the package file | The exporter |
| content.opf | The package: metadata, manifest, reading order | Your title, author and ISBN |
| nav.xhtml | The navigation document — the contents | Your headings |
| XHTML files | The text, usually one per chapter | Your Markdown |
| CSS | Suggested styling the reader may override | Your type settings |
| Fonts, images | Embedded assets | Your files |
How your Markdown maps onto it
Most of the conversion is mechanical, and the parts that are mechanical are the parts you never have to think about again.
| Markdown | In the EPUB | Notes |
|---|---|---|
| # Heading | Chapter boundary and nav entry | This is what builds the contents |
| ## / ### | Sub-entries in the nav | Two levels is usually enough |
| bold / *italic* | strong / em | Real weights if the family is embedded |
| Lists | ul / ol | Indented by the reader, not by you |
| > quote | blockquote | See block quotes and epigraphs |
| Tables | table | Narrow ones survive; wide ones do not |
``code`` | pre / code | Set monospace, and it will still wrap |
| !alt | img with alt text | The alt text is not optional — see accessible PDF and EPUB |
The headings are the load-bearing part. An EPUB's contents is generated from the heading structure, not from a page you wrote by hand, so a manuscript where chapter titles are # in some places and bold text in others produces a contents with holes in it. Headings as book structure is the ten minutes to spend before any of this.
The three routes
| Pandoc | Calibre or Sigil | bukpress | |
|---|---|---|---|
| Where it runs | Your machine, command line | Your machine, desktop app | Browser |
| Setup | Install, then learn the flags | Install | None |
| Typography control | Via a CSS file you write | Via a CSS file you write | Set in the app |
| Font embedding | Manual, in the CSS and the flags | Manual | Automatic |
| Also produces the PDF | Only with a LaTeX toolchain | Poorly | Yes, from the same file |
| Good for | People who like a build script | Repairing an EPUB somebody else made | Getting both files and moving on |
Pandoc's short version, if that is your preference:
pandoc book.md \
--to epub3 \
--output book.epub \
--metadata title="The Quiet Ledger" \
--metadata author="Morgan Reyes" \
--epub-cover-image=cover.jpg \
--css=book.css \
--toc --toc-depth=2 \
--split-level=1That is a working command, and the honest caveat is that book.css is where the actual work lives: every typographic decision you make is a rule you write and then debug across four readers. Pandoc for books covers what that file needs. It is a good tool badly suited to people who wanted to publish a book rather than maintain a build.
The five things that break
Every one of these is a case of the manuscript trying to control a page that, in an EPUB, does not exist.
- Page breaks. A
---page break is meaningful in a PDF and meaningless on a Kindle, where the page boundary moves with the reader's type size. In a well-made EPUB it becomes a chapter break where it separates chapters and nothing at all where it does not. See page breaks in Markdown. - Page numbers. There are none. A cross-reference that says "see page 74" is broken the moment the reader changes the font size — link to the section instead. Page numbers explains where they do and do not belong.
- Fonts. Embed them, and expect to be overruled. Most readers let the reader pick a typeface, and many default to their own. Embed the family anyway, because the readers that respect it are the ones where your book looks like your book.
- Images. Sized for print, they are enormous on a phone and slow to load. Cap the long edge at around 1,600 pixels, use the same colour space throughout, and never rely on an image to carry text — see images in Markdown.
- Wide tables. A six-column table is unreadable at 320 pixels wide. Cut it to three columns, split it into two tables, or accept that it will scroll. Tables has the sizes that survive.
Metadata, cover and the parts stores check
The package file carries what every store reads before a human sees the book. Getting it right in the export is quicker than fixing it in four dashboards.
- Title, subtitle and author exactly as you want them listed. A trailing space here becomes a trailing space in a store listing.
- Language. A missing language code is one of the most common validation failures, and one of the easiest.
- An identifier. Your ISBN if you have one, or a generated UUID if you do not — do you need an ISBN? is a shorter answer than expected.
- A cover image, at 1,600 × 2,560 or thereabouts. Ebook cover sizes covers what survives a thumbnail.
- The rest of the listing metadata — description, categories, keywords — is typed into each store, but write it once and keep it: book metadata.
Validate before you upload
EPUBCheck is the reference validator, and it is the same one the stores run. Running it yourself turns a rejection email in three days into an error message in three seconds.
java -jar epubcheck.jar book.epubThe errors it produces are terse and, once you have seen each one twice, entirely predictable. Common EPUB validation errors is the translation.
Then open the file somewhere real. A desktop preview is not a device: the things you will find on an actual e-reader are the image that is too dark on e-ink, the table that scrolls, and the chapter that starts halfway down a screen. Check one e-ink device and one phone, at the smallest and largest type sizes, and you have covered most of what readers will do to it.
The short checklist
- Every chapter starts with a
#heading, consistently. - Front matter is in the same file, in order — front and back matter.
- Images capped at ~1,600px on the long edge, all with alt text.
- Title, author, language and identifier set in the export, not afterwards.
- Cover attached.
- EPUBCheck clean.
- Opened on a phone and an e-reader, at two type sizes.
And export the PDF from the same manuscript while you are there. Direct buyers want both, stores want the EPUB, and the two files agreeing with each other is only free if they came out of one source — which is the argument for writing the book in Markdown in the first place.