# How to convert Markdown to EPUB

> What an EPUB actually contains, the three routes from a Markdown manuscript to a valid one, and the five things that break on the way.

Canonical: https://buk.press/blog/markdown-to-epub

11 September 2026 · 6 min read

Export the Markdown as a reflowable EPUB 3 with your headings as the document structure, a navigation document generated from them, the typefaces embedded, and the images sized for a small screen rather than for paper. Pandoc will do it from a command line, bukpress will do it in a browser, and both produce the same kind of file: a zip of XHTML that the e-reader lays out for whatever screen it is on.

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 |

"Reflowable" is not a setting somebody turns on. It is what you get when the text is real text in XHTML rather than a picture of a page. A fixed-layout EPUB is a different, rarer product for picture books. If your book is mostly words, you want the ordinary kind.

## 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](https://buk.press/blog/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](https://buk.press/blog/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](https://buk.press/blog/markdown-headings-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:

```
<code>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=1</code>
```

That 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](https://buk.press/blog/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.

1. **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](https://buk.press/blog/markdown-page-breaks).
2. **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](https://buk.press/blog/markdown-page-numbers) explains where they do and do not belong.
3. **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.
4. **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](https://buk.press/blog/markdown-images-pdf)).
5. **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](https://buk.press/blog/markdown-tables-pdf) has the sizes that survive.

The rule underneath all five: anything in the manuscript that specifies where something sits on a page is an instruction the EPUB cannot follow. Structure travels; layout does not.

## 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?](https://buk.press/blog/do-you-need-isbn) is a shorter answer than expected.
- **A cover image**, at 1,600 × 2,560 or thereabouts. [Ebook cover sizes](https://buk.press/blog/ebook-cover-dimensions) 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](https://buk.press/blog/book-metadata-and-categories).

## 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.

```
<code>java -jar epubcheck.jar book.epub</code>
```

The errors it produces are terse and, once you have seen each one twice, entirely predictable. [Common EPUB validation errors](https://buk.press/blog/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

1. Every chapter starts with a `#` heading, consistently.
2. Front matter is in the same file, in order: [front and back matter](https://buk.press/blog/front-matter-and-back-matter).
3. Images capped at ~1,600px on the long edge, all with alt text.
4. Title, author, language and identifier set in the export, not afterwards.
5. Cover attached.
6. EPUBCheck clean.
7. 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](https://buk.press/blog/self-publish-from-markdown) in the first place.

**About this article.** Written by the team that builds bukpress, which turns Markdown into print-ready PDF and EPUB books. Spotted something wrong or out of date? Write to [support@buk.press](mailto:support@buk.press).

## Read next

Explainers 28 August 2026 · 4 min read

## [EPUB or PDF: how to choose, and why you probably want both](https://buk.press/blog/epub-vs-pdf)

Use PDF when the page is fixed and matters: print, handouts, workbooks, anything with a layout the reader must see as you set it. Use EPUB when the text should adapt to the reader's screen and type size, which is every e-reader and almost every ebook store.

[Read it](https://buk.press/blog/epub-vs-pdf)

How-to 30 August 2026 · 4 min read

## [Why your EPUB was rejected, and how to read EPUBCheck](https://buk.press/blog/epub-validation-errors)

Run EPUBCheck before uploading anywhere: it is the same validator the stores run, and it names the file and line for every problem. Errors block ingestion and must be fixed; most warnings are advisory, with the exception of remote resources and missing accessibility metadata, which some stores treat as fatal.

[Read it](https://buk.press/blog/epub-validation-errors)

Guides 30 August 2026 · 4 min read

## [How to turn a Markdown file into a Kindle book](https://buk.press/blog/markdown-to-kindle)

Export the Markdown as a reflowable EPUB with your typefaces packaged in it, add a 1,600 by 2,560 pixel cover, and upload that EPUB to KDP. Amazon converts it to the format the Kindle actually reads. You do not need Calibre, a .mobi file, or Amazon's old .kpf toolchain unless something in the preview is specifically broken.

[Read it](https://buk.press/blog/markdown-to-kindle)

## Write it in Markdown. Ship a book.

bukpress turns the file you are already writing into a typeset PDF and EPUB: your type, your covers, no watermark, ever.

[Get Lifetime, $27 once](https://app.buk.press/signup)