A Quick and Dirty Guide to Creating an EPUB with Pandoc
14 March, 2020
As you may or may not know, I publish an email letter called Weekly Musings. To celebrate the letter’s first year, I recently decided to collect the first 52 essays into an ebook.
With the last few ebooks I’ve published (at least ones in EPUB format), I’ve written them in a desktop application called Sigil. This time ’round, things were a bit different.
The 52 essays that I wanted to collect in the book 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 the deed.
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 book.
- 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, my book was a set of 52 separate files. 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
So, you have everything you need. How do you create an EPUB? Use this command:
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:
--toctells Pandoc that you want to generate a table of contents for the book.--toc-depth=1creates the table of contents using only the first heading in a chapter. You can change that if you want to.--epub-metadata=metadata.yamlpoints to the file containing the information about your book.--epub-cover-image=cover.pngpoints to the image that becomes your book’s cover.--css=book.csspoints to the CSS file that formats your book.-o mybook.epubtells 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 an ebook ready for download by a wider audience.