Can Everton Jones find out how his father stole Emperor Bokassa’s diamonds and, more importantly, where he hid them; before the world and his brother get there first?
Click on the picture link in the sidebar to read an extract of my first novel, which was published by Paradise Press in August 2012.

Thursday, 17 July 2014

How to generate the html table of contents in an e-pub

The html table of contents is a page, near the front of your e-book, which consists of hyperlinks to the various chapters and possibly sections of chapters which follow it in your book. (See my recent post on how to sequence your e-book for more information about where to put the html table of contents and what to include in it.) It is essentially serves the same purpose as the table of contents in a print book and readers will expect to see one. And not only the reader: kindlegen will not like it if there is no html table of contents either! It is completely different in terms of the way it is constructed from the logical table of contents (toc.ncx), which is accessed by the e-reader directly.

Sigil does contain a built-in tool for generating the html table of contents using the various <h1>, <h2>, etc. tags which were used to build the logical table of contents (see my post on how to generate the logical table of contents for more information). If you wanted to use this tool you could access it from the ‘Tools/Table of Contents/Build the html table of contents …’ menu item.

However I am NOT recommending that you do this. In my opinion this leads to far too much complexity in the e-book and is too inflexible. In particular this tool creates a special CSS stylesheet to format the html table of contents and editing this to style yours to your satisfaction would be a lot of trouble. Furthermore, TWO stylesheets is one stylesheet too far, as far as I am concerned. Keep it simple and fewer things can go wrong!

My recommendation is to build the html table of contents yourself. It might sound like a lot of work, but it is fairly straightforward and at least allows you to style and structure it to your satisfaction. In particular, I have some strongly held views on how certain sorts of tables of contents should be styled and the very basic one produced automatically by Sigil just isn’t up to it. (See my post on how to style the html table of contents for more information.)

By all means use Sigil to create the html table of contents, but do it manually, rather than use the automatic tool. You could use Komodo Edit or even a text editor just as well, provided you ‘unpack’ the epub file first.

So, consider first of all a simple e-book with just a linear series of chapters: ‘Chapter1.xhtml’, ‘Chapter 2.xhtml’ etc.

The html table of contents would be impemented like this:

In the html table of contents:

  <p class="contEntry"><a href="Chapter1.xhtml">Chapter One</a></p>
  <p class="contEntry"><a href="Chapter2.xhtml">Chapter Two</a></p>


and In the CSS stylesheet:

.contEntry {}

Notes: in the <p> tag, class="contEntry" applies the CSS style to the paragraph. See my next post about how to style the html table of contents for details of which styles work best. In the <a> tag, href="Chapter1.xhtml" specifies the file which the link jumps to when it is clicked. ‘href’ just stands for ‘hypertext reference’. Because the html table of contents and the various chapters of the ebook are all saved in the same place (the ‘Text’ folder) there is no need to specify a path. The text: Chapter One enclosed by the <a> </a> tags is what will be displayed on the page as the link text.

(* note: 27 August 2014: I have changed the names of the styles so they are consistent with later posts. Where they formerly began: "toc", they now begin with "cont" .)

And that’s really about as much as you need to know to make a basic table of contents. Just make a blank chapter and fill it with hyperlinks to each of the other chapters in your ebook as shown above. Then save it as something like ‘htmlContents.xhtml’, and you’re done.

Treat part titles just like chapters, although they will of course need styling differently, the links will be done exactly as shown above. So an entry in the html table of contents for a part title followed by a chapter might look like this:

<p class="contPart"><a href="partOne.xhtml">PART ONE</a></p>
<p class="contEntry"><a href="Chapter1.xhtml">Chapter One</a></p>

class="contPart" applies the styling using CSS and will require a matching style definition in your stylesheet.

There is a bit more to it if you have subheadings. If you do not, click here to skip the next bit.

To link to a subheading, you need to give each subheading a unique label to identify it. If you have already made the logical table of contents this will have been done. So do that first.

My recommended method is to have the chapter subheadings in paragraph (<p>) tags like this:

In the chapter:

<p class="chapterSubheading">subheading</p>

If it has not already been done, add the label to the subheading In the chapter like this:

<p class="chapterSubheading" id="my_unique_label">subheading</p>

And in the CSS stylesheet define the style like this:

.chapterSubheading {}

notes: the CSS styling is applied using class="chapterSubheading" in the <p> tag. The label (in this example: my_unique_label) can be whatever you want, provided it is a single text string with NO SPACES and provided that EACH label is different (at least within the same chapter).

Then create the link in the html table of contents like this:

<p class="contSubEntry"><a href="Chapter1.xhtml#my_unique_label">subheading</a></p>

and define the style for it in the CSS stylesheet like this:

.contSubEntry {}

notes: In this case the href consists of the chapter filename: Chapter1.xhtml followed by the hash character: # (a required part of the html syntax) and then the label: my_unique_label. Clicking the link will open Chapter1.xhtml and place the subheading labelled my_unique_label at the top of the e-reader screen. I have used a different style so that the entries for chapters and subheadings in the table of contents can be styled differently, for example by setting the subheadings in by a few ems on the left.

Deal with sub-sub-headings and beyond in exactly the same way.

And I VERY STRONGLY RECCOMMEND that you use ‘Chapter1.xhtml’, ‘Chapter2.xhtml’, etc. for your filenames. It will make creating your html table of contents that much easier. Also, when it comes to linking an index or bibliography you will find it is almost essential to follow this scheme. If you have custom chapter fienames you will almost certainly regret it when you come to linking the index. Bear in mind that the chapter filename is completely immaterial to the reader: they never see the actual filename, just whatever text is displayed in the links in the html table of contents and the title line at the top of each chapter. (Or else whatever is within the heading tags used to build the logical table of contents.)

And that’s about it. The html table of contents is ready to go for an epub.

Next steps: style your table of contents. And then, when you have finished the epub and are ready to convert it to a kindle, you will need to restructure the hyperlinks and then re-link the file for the Kindle. Click the links to go to posts I have already published about how to do this.

Index to ‘how to …’ posts:

How to ‘unpack’ an epub file to edit the contents and see what’s inside.
How to understand what is inside an epub
How to link the html table of Contents in a Kindle e-book
How to restructure the html table of contents for a Kindle
How to delete the html cover for a Kindle ebook
How to link the cover IMAGE in a Kindle e-book
How to clean up your MS Word file before your get started
How to markup an MS Word file to identify the formats before importing it into an epub
How to create a new blank e-pub using Sigil
How to import your marked-up MS Word file into your ebook using Sigil
How to create and link a CSS stylesheet in an e-book using Sigil
How to replace the markup with CSS styles in your ebook using Sigil
How to style an e-book so it works with the limited CSS styling available to Kindle e-readers
How to understand the syntax of CSS
How to style Small Caps in an e-book
How to split your ebook up into chapters using Sigil
How to sequence your e-book
How to phrase the copyright declarations etc. in an e-book
How to generate the logical table of contents using Sigil
How to understand toc.ncx in an e-book
How to generate the html table of contents in an e-pub
How to style the html table of contents using CSS
How to create an html cover for your epub using Sigil
How to present references and notes in a book
How to use Mark Up to link notes in your e-book
How to present a bibliography in a book
How to use markup to link entries in a bibliography with the notes section
How to index an e-book
How to use the tools in MS Word to create an index
How to alphabetise an index or bibliography

TinyURL for this post:

No comments:

Post a Comment

Twitter Bird Gadget