Creating ebook format files for Kindle and iBooks using Markdown

In part one, we learned how to write and format your book in Markdown. Next, we’ll walk through how to create the files you need for Kindle, Kobo, Nook, iBooks, and just about every other publishing platform out there. I’ll go into this more later, but for now, it’s worth noting that the two file formats we are targeting are EPUB (the ‘standard’ ebook format), and MOBI (what Amazon uses for their Kindle platform).

If you’ve never done this before, you’ll need to understand a few basic concepts.

  1. Markdown is a writing format, not a publishing format. In order to publish our book, we’ll need to convert it to a format that includes all of the extra stuff necessary for our book including a table of contents, cover image, and metadata (which is just a fancy word for key attributes of your book like author, title, publisher, etc.).
  2. There are two main ebook formats — EPUB and MOBI. EPUB is used by iBooks (as well as other platforms) and is as close to a ‘standard’ ebook format as it gets. MOBI, on the other hand, is required by Amazon for the Kindle. While you can upload an EPUB file to Kindle Direct Publishing, they will just convert it to a MOBI anyway. Personally I prefer creating the MOBI myself so I can be 100% sure that the formatting is what I want.
  3. Creating your EPUB and MOBI files is just one step in the process. The most important step is reviewing and confirming that your formatting is correct. For that, I’ll share some previewer tools that you can use. It’s also great for doing a full read of your book, and for sharing with friends and family pre-publishing.

Now on to the fun!

The steps below assume you have a Mac. If you have a PC, the steps will be similar but there are some details that will vary. Also, all of the tools below are free. Yay!

For this step, we’re going to use Pandoc (a free file converter tool) to create our EPUB file. After that, we’ll use the EPUB file to create a MOBI file (the format we’ll use for Kindle).

We’re also going to use an app on our Mac called Terminal which is a command-line interface. If you’ve never used a command-line interface before it may seem a little daunting, but it’s basically just a text box where you type commands which your computer will run.

Here’s how to get going:

  1. Install Pandoc

2. Open Terminal by pressing Command Space and typing Terminal

3. Navigate to the directory where your Markdown file lives. The easiest way to do this in Terminal is:

  • Type cd
  • Open Finder and drag the directory where your Markdown file lives into Terminal.
  • This will automatically paste the directory name for you.
  • Press Enter

4. Run Pandoc in Terminal to generate your EPUB file:

  • Type pandoc -o OUTPUTNAME.epub where OUTPUTNAME is the name that you want the EPUB file to have, and INPUTNAME is the filename of your book.
  • Typically you want the output name to be the same as the input name, with the exception of the filename extension (e.g. ‘epub’ vs ‘md’).
  • Press Enter
  • Your EPUB file will be generated and saved to the same directory as your Markdown file.

5. If you would like to generate a table of contents and include a cover image, you can add a few switches, like this: pandoc -o OUTPUTNAME.epub --toc --toc-depth=2 --epub-cover-image=COVERIMAGE.png

In the example above, my cover image file is in the same directory as my epub file. If it’s not, you’ll need to include the full file location.

For more switches and other useful documentation check out this article:

On a Mac, it’s as simple as double-clicking the EPUB file. The file will automagically open in iBooks.

On a PC, it’s another story. Here are a few options for previewing your book:

  • Use Calibre. It’s also great tool for editing your ebook and viewing the ‘code’ behind it.
  • Upload to Google Play books. I’ve noticed some issues though with how Google Play formats line breaks coming from Markdown.
  • Download Sumatra PDF.

While Amazon’s Kindle Direct publishing will take an EPUB file and convert it, it’s always better if we create our own so we can preview the file on Kindle and make sure that the formatting is correct. Don’t worry, this is easy-peasy.

  1. Download KindleGen

2. Extract the file by double-clicking on it.

3. Drag the entire KindleGen directory to your Applications folder (you may want to rename it to simply KindleGen before you do this)

4. Create an alias to KindleGen so you can run it from anywhere:

(Note: you can skip this step if you don’t want to mess around with Bash profiles.)

  • Open Terminal
  • Edit your Bash profile (for more info on how to manage your Bash profile, check out this site)
  • Add this line:alias kindlegen=/Applications/KindleGen/kindlegen
  • Now you can just type kindlegen from anywhere in Terminal to load the KindleGen application.

5. Now let’s create your MOBI file:

If you created an alias to KindleGen -

  • Open Terminal
  • Navigate to the directory where your EPUB file lives.
  • Type kindlegen EPUBFILENAME.epub
  • MAGIC!

If you did not create an alias -

  • Open Terminal
  • Navigate to the directory where your EPUB file lives.
  • Drag the KindleGen app from Applications > KindleGen into Terminal. This will automatically add a link directly to the app.
  • Type kindlegen EPUBFILENAME.epub

View the KindleGen Readme to learn more about this tool.

This part is pretty simple: simply download and install Kindle Previewer. (You can also use the Kindle app for Mac or PC, but I like the Previewer since it gives you extra tools that are useful to authors.)

If you prefer to view it on your Kindle directly, you could use the send to Kindle via email feature, but I usually save that for the final read-through, since the previewer is a lot easier to use. You can sideload your MOBI via USB as well.

I write about technology, product management, and writing.