Output EPUB 3 should have a landmarks section in Nav document

[elmimmo]

Pandoc should be generating a landmarks section in the Nav document, with the same information contained in the OPF's guide section.

When exporting to EPUB 3, the resulting OPF document contains EPUB 2's optional guide element, even though, in EPUB 3, the guide and its purpose have been deprecated in favor of the EPUB Navigation Document’s landmarks section, which Pandoc does not currently generate.

It might be considered convenient, for backwards compatibility purposes, that Pandoc generates EPUB 2's guide in EPUB 3 documents. But even though that does not make the document invalid, it is still not the proper EPUB 3 specified way to add that information to the book. I think it is awkward that the information EPUB 2's guide holds is missing in proper EPUB 3 syntax.

As an example, if this is the guide that Pandoc would generate:

<guide>
    <reference type="toc" title="My fist ebook" href="nav.xhtml" />
    <reference type="cover" title="Cover" href="cover.xhtml" />
</guide>

this is what the Nav document's body should contain:

<nav epub:type="toc" id="toc">
  …
</nav>
<nav epub:type="landmarks" hidden="hidden">
  <h1>Special sections</h1>
  <ol>
    <li><a href="cover.xhtml" epub:type="cover">Cover</a></li>
    <li><a href="#toc" epub:type="toc">Table of contents</a></li>
  </ol>
</nav>

In the markup above, … is used to represent what Pandoc already generates.

Note that the landmarks nav element has the attribute hidden="hidden", since it is not supposed to be rendered if the user navigates to this document.

[elmimmo]

Note also that since db90667, the Nav Document will be included in the spine only if you specify --toc on the command line. In you don't, the Nav Document will not be part of the spine and, therefore, the landmarks nav element should not reference the #toc either, or else epubcheck will complain that:

WARNING: nav.xhtml(181,53): hyperlink to resource outside spine 'nav.xhtml'

In other words, then, the markup at the bottom of the comment above is what the Nav document's body should contain if you specified --toc on the command line. If you did not, it should instead be:

<nav epub:type="toc" id="toc">
  …
</nav>
<nav epub:type="landmarks" hidden="hidden">
  <h1>Special sections</h1>
  <ol>
    <li><a href="cover.xhtml" epub:type="cover">Cover</a></li>
  </ol>
</nav>

[andalou]

The problem with this inclusion, is that when converting the epub to
mobi, the mobi doesn't contain any "Table of Contents."

If I remove

<nav epub:type="landmarks" hidden="hidden">
  <h1>Special sections</h1>
  <ol>
    <li><a href="cover.xhtml" epub:type="cover">Cover</a></li>
  </ol>
</nav>

and convert the epub to mobi, then the "Table of Contents" appears!
This is strange!

[elmimmo]

@andalou, What tool did you use to convert from EPUB to mobi? Which Kindle device/app you opened the mobi with? In what menu/place in that app/device you find the "Table of Contents" to be present or missing?

[andalou]

I use "Kindle Previewer" for converting epub to mobi. On "Kindle Previewer" you get three buttons at the top right side. The first button is for "Cover," the middle button is for "Table of Contents," and the third one is for "NCX View."

You can download "Kindle Previewer" from
http://www.amazon.com/gp/feature.html?docId=1000765261

[elmimmo]

TL;DR: If you want the TOC button in Kindle Previewer or certain Kindle's such as Kindle 4 or Kindle Fire 1st Gen, run Pandoc with the --toc argument.

In EPUB there are two distinctive TOCs: the one that the ereader displays with its own native UI (which in EPUB 2 it generates by parsing the NCX Document and in EPUB 3, the Nav Document's <nav epub:type="toc"…>) and optionally an HTML TOC, which is part of the book's content flow (i.e. one that you will eventually stumble onto by turning pages).

Kindle Previewer identifies what I call the native TOC as "NCX View" and the HTML TOC "Table of Contents" [I've edited this paragraph since I had associated both terms reversed].

What you are observing, therefore, is an EPUB that lacks an HTML TOC as part of its content flow. You decide whether to include one or not by running Pandoc with or without the --toc argument, as commented in #1757 (comment).

The Nav Document's landmarks block is where one declares in EPUB 3 that a particular content document is an HTML TOC (see the 2nd code block in #1757 (comment)). If you run Pandoc without --toc, the Nav Document will be omitted from the OPF Document's spine and will also not reference itself in its landmarks block (see the difference between the 2nd code block in #1757 (comment) and the code block in #1757 (comment)).

All EPUB readers that I know support the native TOC but couldn't care less about the HTML TOC (besides displaying it as a normal content document just like any other document in the spine)

Some Kindles, on the other hand, do not support EPUB's mandatory native TOC, and instead have a "Go to: TOC" button that takes you to the HTML TOC if the ebook has one (which again, is optional in EPUB). Such is the case of Kindle 4 Kindle Fire 1st Gen. If you do want one, do add one by running Pandoc with the --toc argument.

As to why you get an HTML TOC in Kindle Previewer if you remove the landmarks nav block, I cannot reproduce that. This is what I tried:

1. Source book.md:

---
title: A Book
lang: es
---

# This is my first chapter

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aut ducimus dolorum dolorem rem eligendi porro placeat nesciunt, sunt consequatur facere officiis rerum quibusdam, praesentium natus nihil, at eius voluptatem vel.

# This is my second chapter

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aut ducimus dolorum dolorem rem eligendi porro placeat nesciunt, sunt consequatur facere officiis rerum quibusdam, praesentium natus nihil, at eius voluptatem vel.

1. Converted with Pandoc with

pandoc -t epub3 --epub-chapter-level=1 -o book.epub book.md

2. Unzipped, edited nav.xhtml removing.

<nav epub:type="landmarks" hidden="hidden">
  <ol />
</nav>

3. Dragged content.opf into Kindle Previewer.

Result: No Table of Contents button, as should be.

[andalou]

TL;DR: If you want the TOC button in Kindle Previewer or certain
Kindle's such as Kindle 4 or Kindle Fire 1st Gen, run Pandoc with the
--toc argument.

I was invoking pandoc with --toc argument. This isn't the problem!

Kindle Previewer identifies what I call the native TOC as "Table of
Contents" and the HTML TOC as "NCX View".

That isn't right. As I've already explained: On "Kindle Previewer" you
have three buttons at the top right side: The 1st button is for "Cover,"
the 2nd button is for "Table of Contents," and the 3rd button is for
"NCX View."
Only when I remove this code:

<nav epub:type="landmarks" hidden="hidden">
  <h1>Special sections</h1>
  <ol>
<li><a href="cover.xhtml" epub:type="cover">Cover</a></li>
  </ol>
</nav>

and convert the epub to mobi, I get the 3 buttons. When I include the
above code I only get the 1st and the 3rd button. Then something isn't
right there!

[elmimmo]

Pandoc does not generate landmarks markup that contains the heading <h1>Special sections</h1>. That was part of my markup's suggestion that Pandoc final implementation did not use (and which is unrelated to you issue). Paste the exact landmarks markup that Pandoc is generating with --toc and that you are deleting.

[andalou]

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

[elmimmo]

That landmarks markup seems correct but, like I said, I cannot reproduce your issue: when I run Pandoc with --toc, I obtain the same landmarks markup as it seems you do and Kindle Previewer 2.923 and 2.94 do let me click all three buttons (Cover, Table of Contents and NCX View). Clicking on "Table of Contents" takes me to the HTML TOC; clicking on "NCX View" takes me to a native TOC.

Please follow the steps I performed as described below, one by one, and report back if you obtain a different result to mine, in order to determine whether the problem is triggered by something in your markdown content, different software versions, operating systems or something else:

1. Create a text file named book.md and, using a text editor give it the following contents:

---
title: A Book
lang: en
cover-image: cover.jpg
---

# This is my first chapter

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

# This is my second chapter

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

2. Place a JPEG file named cover.jpg in the same folder as book.md.
3. In the command line, cd into the directory where book.md and cover.jpg reside and run:

pandoc -t epub3 --epub-chapter-level=1 --toc -o book.epub book.md

4. Open Kindle Previewer and drag book.epub onto its window.
5. Check whether the button "Table of Contents" is clickable.

After doing the above in my computer, all three buttons (Cover, Table of Contents and NCX View) are clickable in Kindle Previewer and clicking each takes me to its respective target.

I tried the above with Kindle Previewer 2.923 and 2.94, Pandoc 1.13.2 installed with Homebrew, on a Mac running OS X 10.10.2. Please provide what you are using.