EPUB to Markdown

How the conversion works

An EPUB file is a zip archive of web pages with a little bookkeeping on top. One file inside, META-INF/container.xml, points to the book's package document, and the package document holds the two lists that matter: a manifest of every file in the book, and a spine that gives the reading order. This tool opens the zip in your browser, follows the container to the package, and walks the spine from start to finish.

Following the spine is the part that is easy to get wrong. The files in an EPUB are not stored in reading order — in the Project Gutenberg edition of The Yellow Wallpaper, for example, the cover page is the last file in the archive but the first page of the book. An archive also holds pages that are not part of the text at all, such as the table of contents. Joining the files in the order the archive happens to store them gives you the wrong book; the spine gives you the right one.

Each chapter is then converted from its HTML. Headings become Markdown headings, paragraphs stay paragraphs, numbered and bulleted lists keep their nesting, blockquotes stay quoted, and italic and bold survive as *italic* and **bold**. Links to web pages are kept; links from one part of the book to another are reduced to their text, since they point at files that will not exist next to your Markdown. Styling — fonts, colours, spacing — is dropped. Plain text output does the same walk and leaves out the Markdown syntax.

Characters that Markdown would read as formatting are escaped, so a sentence that begins "1999." does not turn into a numbered list, and an asterisk in the text stays an asterisk.

What is left out

Images are removed and counted, and the count is shown beside the result. Writing them out as image links would leave every one broken, since the pictures stay inside the EPUB. Pages marked as outside the reading order — notes, extras — and the EPUB 3 table of contents are skipped too, and also counted. Tables come through as one line per row with the cells separated by a vertical bar, which keeps their content without trying to reproduce their layout.

DRM, and other files that will not convert

Books bought from most large stores are protected with DRM: their chapters are encrypted, so there is no text in the file to convert. This tool recognises that and says so rather than producing garbage. Removing DRM is not something it does. Books from Project Gutenberg, Standard Ebooks, and many independent publishers are DRM-free and convert normally.

Some EPUBs scramble their embedded fonts so the fonts cannot be copied out. That is not DRM — the text is untouched — and such books convert like any other. A file that is not a zip, a zip that is not an EPUB, or an EPUB whose package is missing each gets its own message saying which.

Only EPUB is read. Kindle formats such as MOBI and AZW3 are a different and much larger problem, and are not supported.

Private by construction

The conversion runs entirely in your browser. The book is read from your disk into the page and never sent anywhere, so it works offline once the page has loaded. The Markdown it produces can be pasted into the Markdown Preview tool to read it rendered.