Making an ebook — From Markdown to Kindle

Recently I published my first ebook on Amazon’s Kindle Direct Publishing (KDP) platform (the shameless plug will be at the end), and it was an interesting voyage of discovery, so I thought I’d document it here.

Being an old-school coder I wrote my original manuscript using Markdown, specifically the git-flavoured Markdown used in iA Writer, which let me split my writing between desktop, tablet, and phone as needed. Since my book is a collection of short stories I wrote each in it’s own file, starting with a Header 1.

Creating a Manuscript

Once I had my various stories written I needed to combine them all into a single manuscript, from which I would make an ePub file. This manuscript would also have to contain the Dedication, Introduction, Title Page, and so forth. iA Writer can include one document in another using Content Blocks, but this function is limited (only Library files, only using iCloud), and is iA specific in any case.

Instead I used MarkdownPP, a Python based Markdown pre-processor. MarkdownPP knows how to combine multiple documents into one, using the following syntax:

!INCLUDE “../”, 1

The number following the include tells MarkdownPP how to handle included headings. In this case the 1 tells MarkdownPP to increase the heading level of all headings in the included file by 1. In this case it turns the H1’s at the start of my stories into H2's.

Important note: even if you leave blank lines between the !INCLUDE instructions the included files will run together without line-breaks. To fix this I needed to add a line break at the end of every file I was including.

My file was structured using standard Markdown titles to split up the sections, as follows:

> Dedication
# Introduction
Introduction text ...
# Chapter 1
!INCLUDE "", 1
# Chapter 2 
# Back matter
Back matter text ...

Converting to ePub

To convert my full Manuscript to ePub I used the excellent Pandoc — a command-line utility that converts from one document format to another. (I’m barely scraping the surface, Pandoc can do a lot). In this case my Pandoc command was roughly this:

pandoc -o Book.epub metadata.yaml 
--toc --epub-stylesheet=stylesheet.css --toc-depth=2

Basically this instructs Pandoc to output an ePub (it auto-detects the format from the filename after the -o option), by combining my Markdown file ( and a metadata file. The metadata file looks like this:

- type: main
text: The Night Alphabet
- role: author
text: David Donachie
- scheme: DOI
text: doi:10.234234.234/33
publisher: Solipsist Press
rights: Copyright ©2017 David Donachie
date: 2017-09-24

There are many more options you can include in the metadata, including a cover image and ISBN, but KDP requires that you don’t include the cover in the file you upload, so you don’t want to include that.

The rest of the command switches I used are:

  • --toc : create a table of contents
  • --toc-depth : start your table of contents with H2 elements
  • --epub-stylesheet : use this stylesheet

Styling the Epub

You’ll notice that I added my own custom stylesheet to the ePub. This replaces the default stylesheet. I found writing an ePub stylesheet pretty hit and miss. Although most ebook readers support the large majority of current css, some things don’t work as expected — especially when it comes to vertical centring (the accepted answer — making a 100vh high block containing a margin-top: -50% element — worked in iBooks, but not the Kindle previewer).

What I did was create a standard Epub, then rename it to .zip (Epubs are ZIP archives internally), extract the stylesheet, and then play around with it until I got it looking right. Since I was on a Mac I previewed my changes in iBooks, but there are plenty of other ebook readers you could try (such as Calibre).

My own customisations were mostly to do with the size of text on the title page (h1.title and, the appearance of chapter breaks (I turned hr tags into three centred asterisks using ::after), the appearance of the table of contents, and the headings at the top of each story. I also tried very hard to get my dedication to be vertically centred on the page. This worked in iBooks, but (as it turns out) not on Kindle.

If you are interested, my css looked like this:

body { font-family: Georgia,"Times New Roman",Times; margin: 5%; text-align: justify; font-size: medium; }
code { font-family: monospace; }
section h1 { text-align: left; font-size: 4.5em; font-weight: bold; margin-bottom: 0; padding-bottom: 0; font-style: italic; }
h1 + p { margin-top: 0; padding-top: 0; }
h2 { text-align: left; font-size: 1.5em; }
h3 { text-align: left; font-size: 1em; font-weight: bold; }
h4 { text-align: left; }
h5 { text-align: left; }
h6 { text-align: left; }
h1.title { text-align: left; font-size: 2em; margin-top: 50%; } { font-size: 1.3em; } { }
div.title h1 { text-align: left; font-size: 2em; margin-top: 50%; }
ol.toc { padding: 0; margin-left: 1em; }
ol.toc li { list-style-type: none; margin: 0; padding: 0; }
hr { border: none; text-align: center; }
hr:after { content: '* * *'; }
#toc > ol > li > a { display: none; }
#the-night-alphabet blockquote { margin-top: 50%; font-style: italic; }
#the-night-alphabet h1 { text-align: center; font-size: 4em; page-break-after: always; }

Note: page-break-after: always really does force ebook page breaks.

From EPub to MOBI

Small digression here. The Kindle ebook format is, of course, not ePub, but Mobipocket (.mobi). You can convert an ePub to a .mobi file yourself using Amazon’s kindlegen utility, which can be useful for previews, but KDP will happily accept an uploaded ePub for you and convert it to .mobi, so you don’t need to.

Mobipocket can be thought of as an ePub variant, hence my conversion process being to go to ePub first (Pandoc doesn’t output to .mobi), which was easy to preview.

Setting up KDP

So at this point I had an ePub ready to go, the next step was to open a KDP account and set it up. KDP accounts are not your standard Amazon buyer or seller account, but an entirely different service, which you can find at

After you create an account, your first step will be to fill in your tax information. I don’t propose to go through all of that here, but the short version is that there is one set of forms if you are a US tax payer (for which you will need a US tax code to hand), and another if you are not. The exact details will depend on your country of tax residence.

Once you’ve finished with the tax info, you should head to your Bookshelf, where you will see this enticing block:

Naturally you want to click on the Kindle eBook option.

Creating an ebook on KDP breaks down into three sections: Metadata, Content, and Pricing.


In this step you’ll need to enter your book’s title (and subtitle, author info, series, etc.), description, tags, and category. Yes, that means you have to write some killer blurb at this point (cue more fuss than making the ebook) — it’s the text that will appear on the book’s Amazon page, so it is important to get it right.

You also need to enter up to seven keywords, and up to two categories. Amazon emphasises that the choice of categories is of great importance, since it affects how people will find your book. I followed Amazon’s advice — I looked at similar books for sale and noted what categories they were to be found in.

A note on ISBNs: KDP gives you a single free ISBN if you publish a paperback with them, but they don’t do the same for ebooks, instead they give you an AISN (an Amazon ID). You can get your own ISBN if you like, but Amazon won’t do that for you, and suggest that you don’t need to. Buying a single ISBN from the standard outlets can be expensive (£80 here in the UK), but there are cheaper options — for example there are organisations that block-buy ISBNs and make them available to self-publishers at much lower rates, as long as you don’t mind that organisation being recorded as the publisher of your book. I went with the Amazon advice and didn’t bother.

Good news … you can always save this as a draft and come back later.


Once you have all the metadata entered, you move on to the book’s content and cover. This is where you upload your Epub or .mobi (or if you’ve been doing something different to me, your PDF or DOCX). Once you upload KDP will take a moment to prepare its own version of the file, and then make it available for you to see in an online previewer. It will also scan the book for anything it things might be a spelling error — you will need to mark each possible error as approved by you before you can publish.

After the content you move on to the cover. You have two options here, upload an image of your own, or use the Cover Creator, which lets you composite text with a bunch of stock Amazon images.

I uploaded my own image. Images need to be JPEG or TIFF files. KDP advises images 1,600 x 2,560 pixels in size, in RGB, with a minimum resolution of 300ppi. Because I wanted to use my image for a paperback as well, I made it 3,200 x 5,120 pixels (which seems to have worked fine as a 6x9 paperback size).


The final step is pricing. You can pick a single price (for your home region) and let KDP calculate the price in all regions for you, or you can enter a different price for each region, if you want. If prices with odd pennies in the cost bother you, then you may well want to do this.

Followed all of this? If so you can finally hit the publish button, and your Kindle book will appear on Amazon within 72 hours! Congratulations!

Obligatory Self-Plug

Want to get yourself a copy of the book I was creating? It’s name is The Night Alphabet, a collection of 26 short stories that run the gamut from magical realism to SF, passing through horror, fantasy, and pure whimsy on the way.