The simplest way to prepare your book for Kindle — while staying in control of formatting.

Markdown is magic, and enables writers everywhere to do their work free from the distractions of bloated word processors.

Going from Markdown to publishing on Kindle (aka Kindle Direct Publishing or KDP) can be a bit daunting if you’ve never done it before. Fortunately, it’s quite straightforward once you know the steps. Here’s how.


Use proper Markdown formatting.

The first step is to make sure that your Markdown file is properly formatted for Kindle. Primarily this means using proper Markdown tags 1, but it also helps to keep things simple.

Personally I try to stick to:

  • Headers #
  • Bold **
  • Emphasis *
  • Bulleted lists -
  • Numbered lists 1.
  • Hyphens --
  • URLs [link name](
  • Line breaks (simply a space between lines) 2

Header tags in particular are very important as they are used both for the table of contents, and to designate chapters and page breaks. Header 1’s (#) are used for chapters. Header 2’s and below (##, ###) are used for subsections within the chapter.

Add metadata.

The easiest way is to use a simple YAML block at the very top of your document, like this:

title: 'My Book: A Book About Things'
author: Ben Littler

You can also include some metadata — such as a cover image — in the ebook file itself, which I’ll touch on in a bit.

(For more complex usage of YAML in your ebook, see this and this in the Pandoc documentation.)


Create an EPUB file

Since Kindle Publishing can’t deal with Markdown natively, we’ll need to build the files in order to upload our manuscript to their platform.

The first task is to install Pandoc which will handle the heavy lifting for us. 3

Next, we need to generate our epub file using the command line. The simplest command is:

pandoc -o mybook.epub

If you want to tell Pandoc to generate a TOC, and embed a cover image, add a few switches 4 like this:

pandoc -o mybook.epub --epub3 --toc --epub-cover-image=coverimage.png

Create a MOBI file

While this step is optional — KDP will convert your EPUB file when you upload it — I like to generate the MOBI myself so that I can preview it on my Kindle before I upload.

Fortunately, Amazon makes this part easy by providing the Kindlegen tool.

Simply tell Kindlegen to generate your MOBI file by using the following command:

kindlegen mybook.epub


For this, I use a couple of tools:

  • iBooks (Mac and iOS only), for previewing my EPUB
  • Kindle desktop app, for quickly previewing my MOBI
  • Kindle Previewer, for a full read-through of my MOBI before publishing (Previewer can emulate both tablet and kindle devices)

For more on Markdown and ebook publishing, visit

  1. Check out Adam Pritchard’s Markdown Cheatsheet for a good list of the most common Markdown tags. 
  2. If you are formatting your book in typical print fashion, you many want spaces between line breaks, and for each line to be indented. For this, you just need to specify a custom css file. Here’s a sample. 
  3. For a deeper dive into building EPUB files with Pandoc, check out the Pandoc documentation. A few other good resources include ‘How We Automated Our Ebook Builds With Pandoc and KindleGen‘ from the Puppet blog, and ‘Using Pandoc to Build Your ePub eBook‘ from the Storyhack blog. 
  4. Here is a list of my preferred switches

The baby survival gear they didn't tell you about (and sure as sh*t didn't give you at the baby shower) Do Your Hardest Work in the Morning

Leave a Reply

Your email address will not be published. Required fields are marked *