Tag Archives: ePub

Adding a table of contents to your ePUB

With ePUBs it is straightforward to add a table of contents to your book, allowing your readers to quickly navigate within your content. Interestingly how you do it is not a part of the ePUB specification itself, but highlights ePUB’s development from earlier digital book initiatives.

This article assumes you are creating/editing your ePUB source content directly. If generating an ePUB via a development tool (eg Pages, InDesign) then it can automatically generate the TOC for you. However even if doing so this article will help describe what is being built for you.

To help, I’ve included a smorgasbord of sample ePUBs to demonstrate how tables of contents are included. There’s a basic book (single level/standard TOC) as well as books with 2, 3, 4, or 5 level TOCs.
Download the one you want or take the whole pack. Note that because WordPress considers EPUBs a security risk, they’ve all be zipped.

Do I need to do this?

A table of contents is optional (your ePUB is valid and usable without one). What’s more how it actually presents for your readers is dependent on the reader. As such you should decide for each book, and your target market, whether worth the development effort.

How do I do this?

Adding a table of contents to your ePUB has two key steps:

  1. Creating a valid .NCX file
  2. Including the .NCX file in your book

Let’s work through these steps in turn.

Creating a valid .NCX file

The .NCX file defines your table of contents. There’s no rule about what filename to give it, but the default option for most eBooks appears to be TOC.NCX. So we’ll assume we’ve called it that too.

The definition for your TOC.NCX file is not part of the ePUB specification but is instead maintained by the DAISY Consortium and co-opted by IPDF who manage ePUBs for us. Browse the detailed specification and see if you can find out what NCX stands for.

In essence an .NCX file is an XML file. It lists the elements for your table of contents within a simple and standard framework:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx
  PUBLIC "-//NISO//DTD ncx 2005-1//EN" 
  "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<head>
	-- insert required metadata
</head>
<docTitle><text>DOCTITLE</text></docTitle>
<docAuthor><text>DOCAUTHOR</text></docAuthor>
<navMap>
	-- insert required navigation structure
</navMap>
</ncx>

Copy that and use as the basis for your TOC.NCX, while we fill in the missing bits: metadata, title, author, navigation structure.

(1) insert required metadata

Every .NCX file needs to define four metadata elements:

  • dtb:uid – this is the unique ID for your publication.  It needs to match the ID given in content.opf.
  • dtb:depth – this is the number of levels in your TOC. Normally this would be 1 but you can add more levels – see hierarchical contents below
  • dtb:totalPageCount – this is not used: set to zero
  • dtb:maxPageNumber – this is not used: set to zero

For example, here’s the .NCX header for a standard table of contents with only 1 layer of entries.

<head>
	<meta name="dtb:uid" content="a897sad23fd23ds" />
	<meta name="dtb:depth" content="1" />
	<meta name="dtb:totalPageCount" content="0" />
	<meta name="dtb:maxPageNumber" content="0" />
</head>

 

(2) record title and author

The document title and author should match those recorded in the main metadata within content.opf (DC:Title, DC:Creator respectively). Some readers may reference these values when displaying the contents, although those in my limited test suite all seem to ignore these values and focus on those in content.opf.

In the sample ePUBs included with this article I deliberate added “(NCX)” to the end of the title and author in each .NCX file. Just to see if/where it appeared. Never did. But your mileage may vary.

(3) insert required navigation structure

The navMap is where the entries in your table of contents are defined using special XML elements called navPoints.

<navPoint playOrder="x">
     <navLabel>Text to show in the table</navLabel>
     <content src="url" />
</navPoint>

The playOrder is numeric, indicating the sequence that the content elements should be traversed in when navigating.  Note that this does not need to match the order you list them (and they appear) in the TOC. Nor does it need to match the sequence in the <spine> section of content.opf.

My testing (and the OPF specification) indicate that the playOrder is not used to determine the sequence content is browsed. When users move through the content sequentially, this sequence is defined by the <spine> element in content.opf. However, even though playOrder is not used, it is recommended that meaningful values are recorded “just-in-case”. It also ensures your ePUB validation, if using epubcheck, will be successful.

The text will present as entered in your TOC; be mindful that not all readers will have a lot of room so don’t make the entries too long.

The URL needs to be the reference to the file/location that is the target of this TOC entry. This will be the filename if you have created separate chapter files. Else you could reference separate sections within a single document via anchor tags.

For example, here are sample entries from the start of one EBook.


<navPoint playOrder="1">
  <navLabel><text>cover</text></navLabel>
  <content src="00-cover.xhtml" />
</navPoint>
<navPoint playOrder="2">
  <navLabel><text>preface</text></navLabel>
  <content src="10-frontis.xhtml#preface" />
</navPoint>
<navPoint playOrder="3">
  <navLabel><text>credits</text></navLabel>
  <content src="10-frontis.xhtml#credits" />
</navPoint>
<navPoint playOrder="4">
  <navLabel><text>Chapter 1 - Background</text></navLabel>
  <content src="chapter1.xhtml" />
</navPoint>

Note: If using anchor tabs, the other end of the link needs to be to an ID, not name tag. Read this for the explanation.

Including the .NCX file in your book

Only two small changes are made to your existing eBook to include your .NCX content, both made to content.opf:

  • add your TOC.NCX file to the ebook manifest. Application type needs to be
    application/x-dtbncx+xml
  • add a reference to the new TOC.NCX to your ebook spine. This is added as an attribute in your <spine> tag:
<manifest>
  <item href="toc.ncx" id="ncx" media-type="application/x-dtbncx+xml"/>
  ...
</manifest>

<spine toc="ncx">
  <itemref idref="chapter1" />
  ...
</spine>

That’s it. Save CONTENT.OPF, build and test.

Next steps

Once you’ve mastered the basic table of contents, you’re ready to investigate some more advanced options:

hierarchical contents

You can create multiple levels in your table of contents simply by nesting your navPoint elements.

...
<navPoint id="navpoint" playOrder="1">
          <navLabel>Chapter 1
          <navPoint playOrder="2">Section 1</navPoint>
          <navPoint playOrder="3">Section 2</navPoint>
...

Don’t forget to work through the playOrder values to retain a logical sequence to your content. Even though not sure who/where these values are used :-)

How hierachical contents are displayed or navigated depends very much on the reader. It also appears to vary how many levels of content are supported. The standard itself sets no limits (or tells you what to call them: chapter, part, section, ..). However mileage may vary with different readers so don’t go overboard. The following table shows results with the two readers I spend most of my time with: Adobe Digital Editions (ADE) and iBooks (on the iPad). The two columns for ADE show the default view (when first opening your book) and the expanded view.

single level (basic book)
two levels
three levels
four levels
five levels

Notice:

  • for iBooks, it gives up after 2 levels of contents. Unable to find anything official that states that’s a limit, but if aiming for that platform I’d stop at 2.
  • for Adobe Digital Editions, the menu gets a little confused at the deeper levels – notice at 5 levels of contents the first level does not appear. Not sure if anything can be done to fix that, but also reason to avoid going that deep.

The above images are taken from the sample ebooks included with this article. Feel free to use to test how well supported in your chosen reader.

multiple tables (pageLists and navLists)

The standard table of contents is defined within a navMap. This is the complete, logical structure of your book. However the .NCX specification also allows you add two additional types of references to your TOC:

  • pageList – use if needing to offer navigation by page (rather than topic/section). Your ePUB can only include one pageList, and it cannot be hierarchical – one layer only.
  • navList – use if wanting to offer other any other arbitrary collection of topics, for example a list of illustrations or a collection of chocolate recipes taken from your complete recipe book. You can have as many navLists as you want, although they too can only be single level. An additional element, navLabel, can be added to give a title to your collection.

The steps involved in defining and including these tables is complex enough to warrant their own article, coming soon.

Conclusion

A table of contents is a valuable addition to most books, particularly non-fiction or reference titles. Adding one is reasonably simple, and thus worth the effort. However keep to the basics if wanting to be functional in the widest range of readers.

EBook Reader Software Quirks (ADE, iBooks, Stanza, Calibre)

Came across this article on Reader Quirks when trying to determine why my cross-reference links were not working. Didn’t have an answer for that problem but does collate a few peculiarities for the common software-based reader applications:

  • Adobe Digital Editions
  • iBooks
  • Stanza, and
  • Calibre.

May help with your cross-platform testing.

Noticed it hasn’t been updated for 7 months, and has no space for comments. Hence might be some better collection out there somewhere?

ePUB doesn’t like named anchors, use IDs

In a recent ePUB I got lazy. Rather than having separate XHTML files for each section I kept them in larger files and used HTML anchor and name tags to match them up. Problem is this doesn’t work.

What I had was one file per chapter, divided into sections. So my content.xhtml looked like this:

<h1>Chapter Title</h1>
<h2><a name="part1"></a>First Part</h2>
...
<h2><a name="part2"></a>Second Part</h2>
...
<h2><a name="part3"></a>Third Part</h2>
...

This was then accessed from toc.ncx as follows. Important link bits in bold:

...
<navPoint playOrder=11><navLabel><text>Chapter Title</text></navLabel>
  <content src="chapter.xhtml" /></navPoint>
<navPoint playOrder=12><navLabel><text>Part 1</text></navLabel>
  <content src="chapter.xhtml#part1" /></navPoint>
<navPoint playOrder=13><navLabel><text>Part 2</text></navLabel>
  <content src="chapter.xhtml#part2" /></navPoint>
<navPoint playOrder=14><text>Part </text></navLabel>
  <content src="chapter.xhtml#part3" /></navPoint>
...

None of these TOC links work when published as an ePUB (testing in Adobe Digital Editions).

Bit of digging (this helped) and testing, and issue is with the “name” piece. These are not recognised. Instead you need to use IDs.

The good news is you don’t have to change the toc.ncx references, or any other references to the sections. Only the targets need to change. Edit your content from:

<h2><a name="part1">First Part</h2>

To any of the following:

<h2><a id="part1"></a>First Part</h2>
<h2><a id="part1" name="part1"></a>First Part</h2>
<h2 id="part1">First Part</h2>

Obviously the third option (add the ID to the heading itself) is the cleanest. However the first option is the one easiest to implement via global search and replace. Which means it was the one I chose.

ePUB won’t validate because OPF file missing? Check container.xml

Just had a frustrating issue in building a new ePUB where the validation (thanks Threepress) failed saying the OPF file was missing. Even though it was there clear as day in the source files.

If you do have an .OPF file but get this error, then the issue is not with this file at all, but with container.xml (which lives in the META-INF folder). This file does little more than point to your .OPF file. The error therefore arises if it points in the wrong direction.

In my instance the issue was caused by using an ePUB template/shell with a different default value for the filename and path to the .OPF. Note if I’d been paying attention the error message gives you all the information needed to resolve the issue since it reports a different filename for the .OPF to the one created. If they don’t match then container.xml is the culprit.

Here’s the all important line in container.xml. Make sure the name and match match your own construction.

<rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>

How varied is the eBook target market?

if you want to get a quick picture of how wide and varied the eBook market is, visit the UK Book Depository and choose to customise your preferred reader for eBooks. It gives you a great list of devices to choose from:

It’s a wide market!

The iPad is highlighted above as I was looking for books for it. And interestingly, even though it supports the ePUB standard (and they recognise it does on the site) they say they’ve no books. DRM strikes (itself in the foot) again!

ePub Update: Chapter sizes and centering text

Couple of updates as more is uncovered about the joys of eBooks and eBook development.

How big is too big?

Earlier I posted recommendations that you separate ePUB content into separate files to improve eReader performance.  Buried within some ePUB best practices I uncovered at the Adobe ePUB/InDesign site is a more definitive guideline:

  • keep chapters to under 300K (uncompressed)
  • keep images to under 10MB (uncompressed)

Apparently anything bigger upset the SONY eBook Reader.  And we wouldn’t want to do that.

How to centre centred text?

Another post rued an issue with iBooks where content styled as centred refused to appear as such if the iBooks settings  had justification:on.

Well that problem still exists, but there is a simple solution.  Simply place an empty <span> inside of each element styled with text-align:center.  Do so and iBooks will honour your settings.

This fix is one of many gems in the Pigs, Gourds and Wikis article: Beating iBooks Bugs.  The rest of the article is definitely worth a read too.

Building ePUBs with InDesign: Just the Basics

The following started as a quick reference to the basic steps/techniques for creating an ePUB using InDesign 5.  However it’s turned into a mini-epic.  Hence you might prefer to download as a PDFePUB or InDesign project .  They won’t win any design awards but will get you started towards winning your own.
[Note: WordPress won’t permit ePUB files to be uploaded (que?) There is a fix but it’s hard. Instead, download the ePUB link here and remove the .ZIP extension]

Introduction

InDesign is a fantastically powerful tool for generating and organising publishing output that is completely wasted on ePUB development.  This is because the essential premise of an eBook is that the layout is fluid and controlled by the user and the device, not the publisher.

Having said that, InDesign has its benefits, particularly when dealing with extensively text documents, ie the more traditional book or longer format document.  This article covers some of the basic skills uncovered when toying with this powerful application.  It is by no means an InDesign user guide, but hopefully enough to get you publishing.

Which InDesign version?

This document, and my InDesign efforts, have centred on CS5. ePUB support has been available since CS3 but most reviews state iit only got serious from CS4.

Since this article is only about the basics of InDesign it should be applicable to both CS4 and CS5.

How InDesign organises your work

The basic building block in InDesign is a document.  Each time you create one you specify the page layout, then add your content (and extra pages as needed).  You can then publish in all formats, including ePUB.

Optionally you can collect documents into a single book.  In each book you specify the order that documents present in, and choose which document contains the “master” styles to be enforced across all the other documents.  InDesign takes care of applying those styles, making sure page numbers run across all documents, etc.

For ePUBs you can publish from inDesign at the document or book level.  So there’s no real need to go the book route (what do you care about running page numbers?).  The only real benefit is if you publish a book as an ePUB you get a table of contents that matches the document set it contains.  Plus, if your content is long, it does give you, and your target eBook reader, more manageable chunks to work with.

Creating documents and books

To create a document, simply select File > New > Document.  You’ll then get a dialog that has little bearing on any aspect of ePUB development.  As a result I recommend you ignore most if it.  Pick an A4 or A5 page layout for print so you just get some room to work without too many page breaks.

To create a book, select File > New > Book.  And then choose where to save it.

Once saved, what you’ve got is an empty book. To populate your book you then add your documents.  In the book panel, click the plus (+) button.  Then select the document(s) you want to include in your book.  Once selected they’ll be listed in the order added; you can drag and drop to set the required order.


The book panel will list all the documents in your book, and will automatically calculate the page numbers across all the content.  It also shows (by small icon on LHS) which document is picked as the master for your styles: more on that later.

Adding content to documents

InDesign gives you an extensive toolbar to add and manipulate content.  However if working mainly with text we only need a few.  And the real technique (and power of InDesign) is being able to add multiple pages of content in one go.

Now there is probably a better way to do this, but this worked for me.

  1. Get your required content into a text format.  It’s easy to export most documents into text.

  2. Open the document that the content is to be included in.

  3. Select File > Place

  4. In the dialog that appears, select your file, but make sure you have selected the Show Import Options checkbox.


  5. In the Import options, check the options for extra carriage returns match the format of your text import.  By default I found it better to always choose to remove returns at end of every line.  Also check the encoding matches the original.

    What you may find is that you need to trial different settings of these import options to get the best formatted input.  If you pick the wrong one just undo the placement and try again.

  6. Click OK to import your content. 


    You’ll get a floating cursor thingie you can use to drop your content into your document. Now here’s the clever part: press and hold Shift (so the cursor shows a snake-like icon) and then click in the top left corner of your page.

Clicking automatically creates a a text box on the current page and places your content in it. But pressing Shift tells InDesign to create as many pages as are needed to display all your content.


If you need to quickly review your content then use the Story Editor (Edit > Edit in Story Editor).  This gives a plain text view of all your content, allowing you to quickly scroll and edit without being distracted by styles and page breaks.  This is an excellent tool for fixing up unwanted paragraph breaks, repeated footer text included in the body, etc.

You can also use it as a quick way to run through content and apply styles – which we’ll describe next.

Applying styles to documents and books

By default all your content will come in as “Basic Paragraph” style.  You can view the available styles in the Paragraph Styles pane (if not visible choose Window > Styles > Paragraph Styles).

To add a style click the small add icon at the bottom of the pane.  You’ll then get an extensive dialog to tweak to your heart’s content (you can get to the same dialog for an existing style by just double-clicking on it).  InDesign does a decent job of converting your request to CSS when exporting the ePUB; just avoid settings around pagination (eg “start on next odd page”) as these are meaningless in electronic land.

To apply a defined style to content simply click your cursor in the paragraph and then select the required style from the list.  You can do this in both the document window and the story editor window.

If using a book, setup all your required styles in one document.   And then use the book features to apply those same styles across all documents in the book.

  1. In the book panel ensure the document with the required styles is selected as the style source.  It should have the boxy icon appearing in the left column in the book pane.

  2. Click the synchronise button (looks like two arrows attacking each other) at the bottom of the book pane.

Once synchronised, all the styles in your master document will now be available/updated in your current document.  You can then apply them to your content.  If already applied and you’ve made changes to the style, those changes will be automatically applied.

[Note: The same basic principles and features apply to character styles.  However since I've never worked on an ePUB that warranted them I'll leave that as an exercise to the reader].

Adding images

To add an image to a document you use the same Place menu option as for adding text.  The important point, however is to add the image within your text, not in a floating frame.

To add an image inline simply place your cursor where you want the image to appear (be thinking location in text – after this paragraph – not location on page).

Then choose File > Place and locate your image.

Since ePUBs are essentially web pages, use images in the standard web formats (GIF, JPG, PNG, SVG).  I’m sure InDesign can manage converting other formats but why bother if you can the appropriate conversion beforehand.

Publishing your ePub

To publish a document as an ePUB select File > Export for ePUB.


To publish a book as an ePUB select Export Book to ePUB from the book panel menu.

Once selected you get a standard dialog, and most of the options you can leave with their current defaults. The only item to check is the format (use XHTML). However if you make it to the advanced class then there is some useful options in here around re-using external CSS styles, and auto-generating contents.

What next?

Once your ePUB is published open it in your required device and test.  If there are any issues return to InDesign to fix up and re-publish.  A moment’s work.

If there are some fixes that are beyond InDesign then you’ll be pleased to know it generates some of the cleanest XHTML I’ve seen in a long time.  If needing to go “under the hood” you’ll have no problem figuring it out.

Conclusion

This article demonstrates the basic skills needed to generate an ePUB using InDesign.    As you can see, using it for ePUBs is a little like using an aircraft carrier as a harbour ferry.  Sure it will get you there but you’re not really using its full potential.  However it’s strengths in manipulating large text elements  make it a valuable publishing tool to have in your toolkit.

Useful resources

Adobe websites

The Adobe official website has plenty of resources, although most of the good stuff you can access directly from the InDesign help.

http://www.adobe.com/products/indesign/epub/howto/ – collection of authoring guides for ePUBs. Written for CS4 but mostly applicable for CS5 also:

  • How to export for ePUB from InDesign
  • Common questions about exporting EPUB files from InDesign
  • Working with images in InDesign for export to EPUB

http://www.adobe.com/products/creativesuite/design/crossmedia_resources/ebooks_software.
html
– includes some more resources, including videos of the basics. Also of interest here is a topic on how to add the richer, interactive content (video, etc) directly in your publication.

Finally try the official blog. Search on ePUB to see what’s been published:
http://blogs.adobe.com/digitalpublishing/?s=epub

Other websites

http://threepress.org/ – is always a useful site for thoughts on ePUB, not just via InDesign. For example here’s a great article that explains all those ePUB publishing options I said you did not have to worry about.

http://www.pigsgourdsandwikis.com/ – is another great ePUB resource; so good she wrote the book on them. For example, here’s her list of 22 reasons why you need to edit the ePUB source after InDesign finishes its publication:

As a final suggestion, here’s an interesting article on the process of converting a regular book to an eBook. Less about the technical aspects, more about the suggested ways to adjust content and layout to respect the new approach.

Video

Follow the Adobe links above for access to a series of official videos. There’s also a vast collection of quick reference video content on Youtube. Just search for the topic you’re after.

Finally I’d also recommend the Instant InDesign prodcast (http://www.instantindesign.com/). Check out episodes 10 and 11 that dealt specifically with ePUBs.

Single or multiple chapter files in your ePUB?

Up until now I’ve not thought it made much difference in your design whether you publish your ePUB as a single chapter (= single XHTML file) or multiple chapters (= multiple files). Granted you’d lose the ability to provide navigation by a table of contents. But for a book, particularly a fiction novel, how often would you need that? How often do you read a novel and wish you could jump straight to chapter 7?

Well it turns out there is a valid reason for separating your chapters. And that’s for performance. Apologies to whoever first reported this, but apparently when rendering an ePUB and determining pages the base unit to work with is the current chapter file. This means if your entire novel is one chapter that’s how much has to be massaged to work out the page numbers (total and current) each time you change the view or open/close the book.

That makes sense. Your E-Reader is going to have to work harder to know you’re on page 137 of 452, compared to page 23 of 34, in chapter 3.

As a result recommended you always produce your ePUBS with separate chapter files. And note you can do this without necessarily including them in the table of contents. Just ensure each chapter file is listed in content.opf but don’t add them to toc.ncx. The former gives you the navigation through the chapters (so click next at the end of chapter 5 to start chapter 6). The latter optionally gives you a table of contents presented depending on your reader.

How to split a single Indesign document into multiple chapter files

How to split a single Indesign document into multiple chapter files


And for bonus points, if you’re using InDesign there’s an option to automatically split your single document content into separate chapter files. It’s part of the Export to ePUB options:

Issue with centre-aligned text in an ePUB on the iPad

For a while now been puzzled by an issue where centred text in an ePUB book was not appearing as such once the book was viewed on the iPad.

The following images show the issue in a test EBook generated initially in InDesign. All the items in the first (frontis) page should be centered, but aren’t. However the titles in each chapter (added using exactly the same styles!) appear fine.

 
To further confuse, testing the identical book in Adobe Digital Editions shows the required formatting.

So in the immortal words of developers everywhere, what the?

 
It turns out the problem is not in the CSS, or even in the ePUB. But with iBooks. And I thank the gurus at Pigs, Gourds and Wikis for pointing me in the right direction.

The solution is “Apple simple”, meaning its easy/obvious once you’ve been told where to look. But impossible to fathom before then.

 
Turns out iBooks has an “override” setting for justifying text. And this for some reason messes with my text-align:center. settings. The value can be changed within the Settings application. To get the centred text to appear as expected I needed to turn full justification off.
 
To demonstrate, following are the same pages from the start of the article, but now with the setting changed. Nothing was modified in the ePUB itself, only the iBooks configuration.
 

All is right with the world.