asciidoctor-epub3 and TOC for Kindle (mobi); preparing your book for publication on Kindle

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

asciidoctor-epub3 and TOC for Kindle (mobi); preparing your book for publication on Kindle

There have been a few posts here on this forum about TOC (table of contents) for ePubs and for Kindle (mobi).

Dan has taken the view that no HTML TOC is needed within an ePub because ePub readers create their own TOC, which is usually available from the ebook reader's menu. A fair point of view. However, on the other hand, I would make these points (as others have on this forum):

* Kindle publishing guidelines recommend that a HTML TOC be embedded in the book.
* Some of the earliest Kindle readers (which Amazon still has to support) don't create an automatic TOC that is available through the Kindle reader's menu. So an embedded HTML TOC is all that those readers get.
* Readers (even technical ones) expect to open a book and see an TOC. If they don't, and don't know that that feature might be available through the menu of their Kindle reader, they may be provoked to leaving a Amazon review of your book along the lines of "I would have given this book 5 stars, but I'm giving just a 1 star review because it doesn't have a table of contents, come on!"

Others might find it useful how I prepared my book for publication on Kindle:

1). Build your book for Kindle using asciidoc-epub3. Be sure to use the flag "-a ebook-extract" to extract the contents of the intermediate ePub file:

  asciidoctor-epub3 -d book -a ebook-format=kf8 -a ebook-extract book.txt
This will create, book-kf8.epub and a directory named book-kf8. Delete the files and book-kf8.epub. We'll regenerate them once we've added a HTML TOC to the book.

2). Look inside the directory book-kf8/OEPS for the file package.opf. Open package.opf in a text editor. The first thing to note is that a HTML TOC has been generated (nav.xhtml)! In package.opf you will find this entry under the <manifest> tage:

  <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>

The only thing missing is that it has not been added to the "spine" of the ebook. In package.opf add this to the <spine> tag:

  <itemref idref="nav"/>

3). Add this HTML snippet to the nav.xhtml (just above the existing <nav> element) file:

  <nav epub:type="landmarks" class="hidden-tag" hidden="hidden">
  <ol class="none" epub:type="list" hidden="hidden">
  <li>Table of Contents</li>

This will make the "Table of Contents" entry in the mobi metadata show as "specified". Omitting it will make the TOC metadata show "unspecified".

4). Recreate book-kf8.epub from the folder book-kf8 by zipping it (you can use a utility like eCanCrusher).

5). Lastly, convert the epub file to a Kindle mobi file using Amazon's kindlegen utility:

  kindlegen book-kf8.epub -o
6). Open and test your book in the Kindle Previewer app.
[1] Kindle: Create a Table of Contents with a Navigation Document []
[2] Editing inside the ePUB package []