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:

• A file that makes up your book. That file can be in any format that Pandoc supports. As I mentioned earlier, my book was a Markdown file.
• A CSS file to format your book. Here’s the file I used with my books.
• A metadata file, which contains information about the book (like title, author, copyright). Here’s an empty metadata file that you can use as a template.
• An image for your book’s cover. that can be a JPEG or PNG file.

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:

• --toc tells Pandoc to generate a table of contents for the book.
• --toc-depth=1 creates the table of contents using only the first heading in a chapter. You can change that if you want to.
• --epub-metadata=metadata.yaml points to the file containing the information about your book.
• --epub-cover-image=cover.png points to the image that becomes your book’s cover.
• --css=book.css points to the CSS file that formats your book.
• -o mybook.epub tells Pandoc to save your book with the name mybook.epub. You’ll want to change that …

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.