A Quick and Dirty Guide to Creating an EPUB with Pandoc

(Note: This article was first published, in a slightly different form, at Open Source Musings and appears here via a Creative Commons BY-NC-SA 4.0 license.)

As you may or may not know, I publish an email letter called Weekly Musings. To celebrate the letter’s first and second years, I decided to collect the first 104 essays into a pair of ebooks.

With the last few ebooks I’ve published (at least ones in EPUB format), I’ve written them in a desktop editor called Sigil. With the Weekly Musings collections, though, things were a bit different.

The essays that I collected in the books were individual files formatted with Markdown. Converting them to HTML (which is file format in which Sigil stores chapter files) and importing them into Sigil would have been a bit of a chore. Instead, I turned to Pandoc to quickly do create the ebook.

Pandoc, if you’re not familiar with it, is something of a Swiss Army Knife for converting between markup languages. Pandoc can also create EPUB files.

Let’s look at how I did it.

What You’ll Need

Before you can create the ebook, you’ll need to install Pandoc on your computer.

You’ll also need:

As I mentioned at the beginning of this article, each book is a set of 52 separate files. To both of them, I also added an introduction, an author bio, and a colophon. I had to combine all those files into one. I’ll explain how to do that in a future article.

Doing the Conversion

Now that you have everything you need, use this command to create the EPUB:

pandoc --toc --toc-depth=1 --epub-metadata=metadata.yaml --epub-cover-image=cover.png --css=book.css -o myebook.epub

Let’s break the command down:

If everything goes well, you’ll have an EPUB file within a few seconds.

To test your book, open it in an ebook reader. You should also run it through an EPUB validator to make sure there are no problems with the file.

This definitely wasn’t the most elegant way to create an ebook. While quick and dirty, the job got done and I had a couple of ebooks ready for download by a wider audience.