How to build an Amazon Kindle book via HTML and OPF

I’ve recently published a couple of books in Kindle format on Amazon. The latest is Words Words Words: A Trilby Trench adventure. It took me a while to get the publication process to work, so I’ve jotted down my notes in case they’re useful to others.

Please be aware that these are just my own notes, and are not intended as any sort of official or fail-safe way of moving content to Amazon.

Overview of my writing and publication process

I write my books online in Google Docs. That means I can access the content from any computer at any time, no matter where in the world I happen to be, provided I’m online. Google Docs also has an offline capability, but I haven’t used it extensively.

For the conversion to Amazon Kindle format, I use straight HTML rather than a Word doc or other format. I convert the content from my Google Docs file to HTML, using a Chrome add-on: GD2md-html. Why use the add-on instead of Google Docs’s own export to HTML functionality? Because I want a single, simple HTML file that contains just the content with minimal markup.

Then I hand-craft the files for the table of contents and other metadata.

Here are my step-by-step notes, in the hope they’re useful to other people.

Step 1: Create an HTML file containing the content of your book (your-book.html)

My content is in Google Docs. This is the way I convert it to HTML:

  1. In Google Docs, make sure all chapter titles are at heading level 2.
  2. Convert the Google Docs content to HTML. I use the Chrome add-on GD2md-html, with its default settings for the HTML conversion.
  3. Save the result on your computer as an HTML file. Use any file name you like. For example, your-book.html.
  4. Open the HTML file in your favourite text editor.
  5. Make sure the character encoding in your editor is set to something other than UTF-8. See Amazon’s documentation. (I ran into trouble when uploading my files to Amazon because the apostrophes, ellipses, etc, were using the default character encoding for my editor, which was UTF-8. On the Mac, Latin-1 (ISO-8859-1) worked for me.)
  6. Optional, for better HTML semantics: Change all em> to i>
  7. Remove the heading level 1 element that contains the title of the doc: <h1>Remove this element containing your title</h1>
  8. Add an HTML <head> and <title> element containing your title. Example:
    <html>
      <head>
        <title>Put your title here</title>
      </head>
      <body>
      .
      .
      .
      </body>
    </html>
    
  9. Add an HTML <body> tag directly after the </head> tag, as shown in the example above.
  10. Scroll to the bottom of the doc, and add the closing </body>and </html>tags:
    </body>
    </html>
  11. Change all the <h2> elements that contain your chapter titles, to include a page break element and an id attribute, like this:
    <mbp:pagebreak/>
    <h2 id="chapter-1">Chapter 1</h2>
    

    And:

    <mbp:pagebreak/>
    <h2 id="chapter-2">Chapter 2</h2>
    

    And so on.

  12. Optional: Add a welcome blurb at the top of the page, before your first chapter. Something like this:
            <h2 id="welcome">Welcome!</h2>
            <p>Welcome to <i>Your book title</i>, the crazy adventures
            of a possum in a puddle.</p>
    
  13. Save the changes to your-book.html.

Here’s a minimalist sample for your-book.html:

<html>
  <head>
    <title>Put your title here</title>
  </head>
  <body>
    
    <mbp:pagebreak/>
    <h2 id="welcome">Welcome!</h2>
    
    <p>Welcome to <i>Your book title</i>, the crazy adventures
    of a possum in a puddle.</p>
    
    <mbp:pagebreak/>
    <h2 id="chapter-1">Chapter 1</h2>
    
    <p>Your content, including simple HTML markup such as <i>italics</i>.</p>
    
    <mbp:pagebreak/>
    <h2 id="chapter-2">Chapter 2</h2>
    
    <p>More content.</p>
    
    <p>THE END</p>
  
  </body>
</html>

For more information, see Amazon’s guide to supported eBook formats.

Step 2: Create a table of contents file (toc.html)

  1. Copy the example toc.html content below, and save it with file name toc.html, in the same directory as your HTML content file (your-book.html).
  2. Edit the file in your favourite text editor.
  3. In all the href attributes, change your-book.html to the name of your HTML content file.
  4. In all the href attributes, change the chapter IDs and chapter names if necessary, to reflect the ones you’ve used in your HTML content file.
  5. Add more list items to reflect all the chapters in your HTML content file.

Example of toc.html – unfortunately, I had to paste this as an image, because WordPress won’t let me include the HTML for this file. (I tried all sorts of things, escaping characters, using HTML entities, etc, but nothing worked for this particular set of code.)

For information about the “landmarks” entry and other details, see Amazon’s guide to creating a table of contents.

Step 3: Create an OPF file (your-book.opf)

The Open Packaging Format (OPF) file is an XML file that contains metadata describing your book.

  1. Copy the example OPF content below, and save it in the same directory as your HTML content file. The part of the file name must be the same as your HTML content file. So, if your content file is your-book.html then the OPF file must be your-book.opf.
  2. Edit the file in your favourite editor.
  3. Change “Your Title” to the title of your book.
  4. Change “Your Name” to your name, such as “Sarah Maddox”.
  5. Change “Name, Your” to your name with your last name first, such as “Maddox, Sarah”.
  6. Change “your-book.html” to the file name of your HTML content file.

Example OPF file:

<?xml version="1.0" encoding="UTF-8"?>
<package unique-identifier="uid">
  <metadata>
    <dc-metadata xmlns:dc="http://purl.org/metadata/dublin_core" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/" xmlns:opf="http://www.idpf.org/2007/opf">
      <dc:Language>EN</dc:Language>
      <dc:Title>Your Title</dc:Title>
      <dc:Publisher>Your Name</dc:Publisher>
      <dc:creator opf:role="aut">Name, Your</dc:creator>
    </dc-metadata>
    <x-metadata>
      <output encoding="utf-8" output="text/html"/>
    </x-metadata>
  </metadata>
  <manifest>
    <item id="table-of-contents" properties="nav" href="toc.html" media-type="application/xhtml+xml"/>
    <item id="html" href="your-book.html" media-type="text/x-oeb1-document"/>
  </manifest>
  <spine>
    <itemref idref="table-of-contents"/>
    <itemref idref="html"/>
  </spine>
  <guide>
    <reference type="toc" title="Table of Contents" href="toc.html"/>
    <reference type="text" title="Beginning" href="toc.html"/>
  </guide>
</package>

For more information about OPF files, see the epub-boilerplate wiki on GitHub and the section titled “Finish your TOC” in the Amazon guide.

Step 4: Create a toc.ncx file – not sure this is needed

I’m not sure that you need a toc.ncx file for Amazon Kindle books. The Amazon docs seem to imply that you don’t need one. But I created one anyway, and included it in the upload of my book. I figure it may be useful for older types of devices that people may be using to read the book.

Below is an example of a toc.ncx file. Note the two attributes that increase incrementally: playOrder and the chapter number.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
"http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
 
<ncx version="2005-1" xml:lang="en" xmlns="http://www.daisy.org/z3986/2005/ncx/">
 
  <head>
<!-- The following four metadata items are required for all NCX documents,
including those conforming to the relaxed constraints of OPS 2.0 -->
 
    <meta name="dtb:uid" content="uid"/> <!-- same as in .opf -->
    <meta name="dtb:depth" content="1"/> <!-- 1 or higher -->
    <meta name="dtb:totalPageCount" content="0"/> <!-- must be 0 -->
    <meta name="dtb:maxPageNumber" content="0"/> <!-- must be 0 -->
  </head>
 
  <docTitle>
    <text>Your Title</text>
  </docTitle>
 
  <docAuthor>
    <text>Name, Your</text>
  </docAuthor>

<navMap>
	<navPoint class="toc" id="table" playOrder="1">
		<navLabel><text>Table of Contents</text></navLabel>
		<content src="toc.html" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="2">
		<navLabel><text>Welcome</text></navLabel>
		<content src="your-book.html#welcome" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="3">
		<navLabel><text>Chapter 1</text></navLabel>
		<content src="your-book.html#chapter-1" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="4">
		<navLabel><text>Chapter 2</text></navLabel>
		<content src="your-book.html#chapter-2" /> 
	</navPoint>

</navMap>

</ncx>

Step 5: Zip all the files (your-book.zip)

Zip the following files into a zip file named something like your-book.zip (the name of the zip file is up to you):

  • your-book.html (the file name is up to you, but the extension must be .html)
  • toc.html (use this file name)
  • your-book.opf (the file name is up to you, but the extension must be .opf)
  • toc.ncx (use this file name)

Step 6: Upload the zip file to Amazon

  1. Go to Kindle Direct Publishing. Sign in, or create an account if you don’t yet have one.
  2. Follow the prompts to create a new ebook and supply the requested information.
  3. When the Upload eBook manuscript option appears, click it.
  4. Follow instructions to upload your zip file.

Troubleshooting

When things go wrong, the error message you get from KDP isn’t very helpful. It basically tells you that there was an error processing your file, and you should check your files.

A couple of issues I had, which may help you diagnose any problems you come across:

  • Check the little things, like syntax bugs a copy/paste errors. In the book’s content file, one of the id attributes for my chapter headings was wrong. In effect, I had two headings with id="chapter-2", and none with id="chapter-2". KDP was happy when processing the content file alone, but gave an error as soon as I tried to hook it up to the toc.
  • Character encoding is a hassle. I ran into trouble with apostrophes, ellipses, etc, because the default character encoding for my editor was UTF-8. It’s safest to set your editor to use ANSI. See Amazon’s documentation.

Hint: If things go wrong, try uploading just your HTML content file

If you can’t get your toc and OPF files to work, one trick is to first upload just your HTML content file to Amazon KDP, then download the resulting Kindle file from Amazon and adapt it.

  1. Go to Kindle Direct Publishing (KDP). Sign in, or create an account if you don’t yet have one.
  2. Follow the prompts to create a new ebook and supply the requested information.
  3. When the Upload eBook manuscript option appears, click it.
  4. Follow instructrions to upload your HTML file.

Amazon KDP takes your HTML and creates the basic set of files that it needs to make a Kindle book. You can now make use of those files. So, when the upload is finished, follow these steps to download the results as a zip file:

  1. Still in KDP, scroll down to the Kinde eBook Preview section and click Preview on your Kindle device. A small section open on the page.
  2. In the section that opens on the page, click the HTML link in the first bullet point. (The text is “Step 1: Download your converted book file: HTML or MOBI.)
  3. Wait for the zip file to download, then unzip it on your computer.

Now you can continue working on the files as described earlier in this post, and upload them again as a zip file. You can download and upload as often as you need.

Other useful resources

Perry Garvin has written a useful article on making a Kindle book with HTML and CSS. I follow a different procedure from the one mentioned in that post, but the description of the files, and the sample doc set are very useful.

Amazon’s KDP Jumpstart is a good entry point into the world of Kindle Direct Publishing.

 

Advertisements

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 April 2018, in book, Fiction, technical writing and tagged , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s

%d bloggers like this: