4

My ebook has sections and chapters within them. Section 1 has an overview page and then chapter 1 follows. When I download my book from Amazon, it starts at the beginning of chapter 1 so the user misses the preface and the section text.

In Section 5.3 of the Amazon Kindle Publishing guidelines (https://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines.pdf)

it says that "Guide items are an optional feature in the EPUB format but are highly recommended. Kindle provides support for the cover, TOC, and start reading location (”Go to Beginning”) guide items.

I'd like to specify the 'start reading' location but can't find an example how to do that.

How is this done?

Ralf Stubner
  • 26,263
  • 3
  • 40
  • 75
sliptonic
  • 460
  • 3
  • 11
  • apparently, [it's complicated](https://www.mobileread.com/forums/showthread.php?t=212660)? – mb21 Sep 14 '18 at 16:48

1 Answers1

2

An EPUB book is just a ZIP file, so you can unzip it and look at the files inside. A sample EPUB I created with bookdown contained a file content.opf with this <guide> element:

  <guide>
    <reference type="toc" title="A Minimal Book Example" href="nav.xhtml" />
  </guide>

According to https://ebookflightdeck.com/handbook/guide the cover and text guides would look something like this, where text corresponds to the 'start reading location':

<guide>
    <reference type="cover" title="Cover Image" href="cover.xhtml"></reference>
    <reference type="toc" title="Table of Contents" href="toc.xhtml"></reference>
    <reference type="text" title="Startup Page" href="chapter1.xhtml"></reference>
</guide>

Of course, the explicit href has to be adjusted to what is found in the EPUB.

Alternatively, you could use EPUB3 rules and add landmark items to nav.xhtml, c.f. https://ebookflightdeck.com/handbook/landmarks. Here bodymatter is probably what is needed. This might fit better, since bookdown uses EPUB3 by default. In my example EPUB generated with pandoc 2.2.1 I again get the toc, but nothing else:

<nav epub:type="landmarks" hidden="hidden">
  <ol>
    <li>
      <a href="#toc" epub:type="toc">Table of contents</a>
    </li>
  </ol>
</nav>

To get this to work I had to use:

bookdown::epub_book:
  toc: yes

pandoc >= 2.3 supports better support for specifying the different sections of an ebook using the epub:type attribute.

I am not sure how relevant this is for the kindle production, though, given this quote from the above linked publishing guidelines:

Publishers do not need to define a start reading location because Amazon does this during the upload process.

mb21
  • 34,845
  • 8
  • 116
  • 142
Ralf Stubner
  • 26,263
  • 3
  • 40
  • 75
  • According to https://github.com/jgm/pandoc/issues/1757, pandoc should produce a `landmark` item... what version are you guys using? – mb21 Sep 14 '18 at 14:45
  • @mb21Good question! I am using pandoc 2.2.1. see the updated answer. BTW, according to the cited issue, the `landmark` item should not be empty. But a "start reading location" is also not expected, correct? – Ralf Stubner Sep 14 '18 at 14:53
  • I think you have to pass pandoc the `--toc` option. – mb21 Sep 14 '18 at 14:53
  • What would the "start reading location" look like in the code? If pandoc does it, you should find it in this file (Ctrl-F): https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/EPUB.hs – mb21 Sep 14 '18 at 14:55
  • 1
    @mb21 Thanks, `--toc` helps to some extend. I will update my answer. As for "start reading location", I think this should be `bodymatter`. I can find that string within `EPUB.hs`, but I cannot decipher under which conditions it is used. – Ralf Stubner Sep 14 '18 at 15:00
  • 1
    The condition is basically "if you don't add special keys to your headers with attributes" ;) so e.g. `echo '# hi' | pandoc --toc -o test.epub` will put `` in `ch001.xhtml` – mb21 Sep 14 '18 at 15:11
  • @mb21 Not for me. `unzip test.epub && grep bodymatter -r .` yields nothing. – Ralf Stubner Sep 14 '18 at 15:20
  • 1
    that was only [added](https://github.com/jgm/pandoc/commit/7318bc91ce58bb6c39e556e334f278e590439c3f) in pandoc 2.3, see http://pandoc.org/MANUAL.html#the-epubtype-attribute – mb21 Sep 17 '18 at 06:28