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.mobi, book-kf8.epub and a directory named book-kf8. Delete the files book.mobi 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: