HTML TOC and asciidoctor-epub3

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

HTML TOC and asciidoctor-epub3

redsymbol
Hello,
This question is for the asciidoctor-epub3 tool:

https://github.com/asciidoctor/asciidoctor-epub3

I'm using it to generate EPUB, MOBI, and KF8 output. As well as distributing each of these to the reader, I plan to upload one of them to Kindle Direct Publishing (my understanding is that it can accept any of these formats).

In addition to the built-in logical/NCX table-of-contents generation (which works perfectly), I'd like to add an inline, HTML TOC page to the beginning of the ebook. This distinction is described here:

https://kdp.amazon.com/en_US/help/topic/A140JEYVI0P8KQ

So far I have not found a way to accomplish this using asciidoctor-epub3. Can anyone recommend a good approach (or point out an option I missed)?

Thank you,
Aaron
Reply | Threaded
Open this post in threaded view
|

Re: HTML TOC and asciidoctor-epub3

mojavelinux
Administrator
Aaron,

I left the in-document TOC out of Asciidoctor EPUB3 because I'm strongly opposed to its use. I think it infringes on the role of the navigation menu provided by the reader app. I recognize this is a personal preference as a reader, though I believe it's a practical position.

Having said that, I understand that there are users who do want it or may have to include it to satisfy a requirement beyond their control. For that, we could consider a special document attribute which enables the in-document TOC. We'd need to decide the following:

* what attribute name to use
* how the HTML should be styled by default

Cheers,

-Dan


On Wed, Jul 19, 2017 at 11:04 AM, redsymbol [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello,
This question is for the asciidoctor-epub3 tool:

https://github.com/asciidoctor/asciidoctor-epub3

I'm using it to generate EPUB, MOBI, and KF8 output. As well as distributing each of these to the reader, I plan to upload one of them to Kindle Direct Publishing (my understanding is that it can accept any of these formats).

In addition to the built-in logical/NCX table-of-contents generation (which works perfectly), I'd like to add an inline, HTML TOC page to the beginning of the ebook. This distinction is described here:

https://kdp.amazon.com/en_US/help/topic/A140JEYVI0P8KQ

So far I have not found a way to accomplish this using asciidoctor-epub3. Can anyone recommend a good approach (or point out an option I missed)?

Thank you,
Aaron



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/HTML-TOC-and-asciidoctor-epub3-tp5746.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: HTML TOC and asciidoctor-epub3

redsymbol
Thanks for replying, Dan.  I *strongly* agree with your sentiment. The navigation menu is better in every way, and it'd be far better if everyone used it instead.

Unfortunately... not everyone realizes their reader even has a built-in nav.  If I sell it on Amazon without an in-document TOC, sooner or later someone would post a review like "knocking off a star because this book doesn't have a table of contents".  It's frustrating. Even though my audience is technical (the book's about advanced Python programming), I'm sure someone would misunderstand, get mad, and blame me.

So I'm grateful you're open to adding an option for it. I have no preference for styling, so long as it looks okay (and everything I've seen asciidoctor-epub3 produce is gorgeous). My only request is that it list sections as well as the chapters.  I don't really know Ruby, but am delighted to help in any way I can.

Cheers,
Aaron