Publishing Technical Documents with ePub

Prerelease Version

Navigation Files

After creating an Open Package Format (OPF) file, your ePub now has metadata, a complete list of content files, and an order for ePub Reader apps (“Readers”) to present this content. What it doesn’t have is a way for users to navigate to different points within the content (i.e. a Table of Contents). For that, you need to create navigation files (and link back to them in the OPF file, if you haven’t already).

As mentioned in the previous chapter, Version 2.x of the ePub spec requires an NCX file, which is XML file that contains the data for the Table of Contents (TOC). Version 3.x still allows you to include this file for backwards compatibility, though it is now recommended that you use a specially structured XHTML file for the TOC data, instead of using the NCX format.

The NCX file format is described here and the complete NCX specification document is here. Note that the ePub specification does not require a complete NCX document including meta data. Rather, it has repurposed the format for its own needs and drops nearly all of the meta data and some of the other elements from NCX (see here for details).

NCX Elements in Detail

This may not be that interesting for those that are working towards Version 3.x documents, but an overview of the organization of the format may be helpful since this same organization is (mostly) carried forward into Version 3.x, even if the implementation is in XHTML rather than custom XML. If you still aren’t interested, feel free to skip ahead.

<ncx> element

Example:

<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1" xml:lang="en">

This is the root XML element. You will likely be using this same version, namespace, and other attributes over and over again.

<head> element

Example:

<head> . . . </head>

A wrapper element for all of the meta data in this file.

<meta> element

Examples:

<head>
    <meta name="dtb:uid" content="http://www.gutenberg.org/ebooks/832"/>
    <meta name="dtb:depth" content="2"/>
    <meta name="dtb:generator" content="EpubMaker 0.3.20a6 by Marcello Perathoner &lt;webmaster@gutenberg.org&gt;"/>
    <meta name="dtb:totalPageCount" content="0"/>
    <meta name="dtb:maxPageNumber" content="0"/>
</head>

The meta element should seem pretty familiar and has just two attributes, the name of the meta field and its content. All of the example names are listed in the NCX specification document, but only dtb:uid is actually required for ePub documents and its content needs to match the value in the dc:identifier metadata element of the OPF file.

dtb:depth is also important for many Readers as it tells some Readers how far down the navigation map element tree it should go when building the TOC. This may not be honored by all readers, however. The remaining meta fields may be helpful for some readers, but likely are only included more as part of the convention then because of any real need for most Readers.

<docTitle> element

Example:

<docTitle>
    <text>Robin Hood</text>
</docTitle>

This is a wrapper element for the title used in the TOC. This contains, at minimum, a <text> element with the title. In the DAISY specification document, <audio> elements can also be included here (for the benefit of audio books), but this part of the spec is specifically excluded from ePub. This is also true for other content elements in the NCX format.

<docAuthor> element

Example:

<docAuthor>
    <text>J. Walker McSpadden</text>
</docAuthor>

This element is included as part of the ePub implementation of the spec, and is added to the examples, but is not a required element may not be used by all Readers.

Example:

<navMap>
  <navPoint id="np-1" playOrder="1">
    <navLabel>
      <text>ROBIN HOOD</text>
    </navLabel>
    <content src="html/chapter-1.xhtml"/>
  </navPoint>
  <navPoint id="np-2" playOrder="2">
    <navLabel>
      <text>CHAPTER I</text>
    </navLabel>
    <content src="html/chapter-1.xhtml#chapteri"/>
    <navPoint id="np-2-1" playOrder="3">
      <navLabel>
        <text>Section 1</text>
      </navLabel>
      <content src="html/chapter-1.xhtml#section1" />
    </navPoint>
  </navPoint>
</navMap>

This is a wrapper element for the element data tree used to generate the TOC. Each navPoint inside the navMap is used to generate an entry in the TOC. navPoint elements can be nested inside of each other to allow, for example, the ability to list all of the major subheadings inside each chapter of the book rather than being limited to the start of the chapter. The src URLs used in the <content> elements must be consistent with the content HTML in your ePub. If you go linking to files or internal anchors that do not exist in your HTML, you will cause issues.

Example:

<navPoint id="np-1" playOrder="1">
    ...
</navPoint>

navPoint elements have two key attributes: id which needs to be unique for each navPoint in the NCX and playOrder which is used to put all of the navPoint elements in the correct reading order. playOrder is not required in the ePub implementation of the specification, but if included, its values must be a positive integer starting with “1” as the first element.

The other elements in the navMap tree (like content) should make sense from the example. The specifications documents can provide you with more detail, should you need it.

<pageList> elements

Example:

<pageList>
    <pageTarget id="p1" type="normal" value="1">
        <navLabel><text>1</text></navLabel>
        <content src="content.html#p1"/>
    </pageTarget>
    <pageTarget id="p2" type="normal" value="2">
        <navLabel><text>2</text></navLabel>
        <content src="content.html#p2"/>
    </pageTarget>        
</pageList>

The pageList element tree is not required by the ePub specification. It is used to provide a direct link between pages in a printed version of the content and locations in the ePub version of the content. This may not be used by all Readers but is carried over into Version 3.x of the specification in a different form. The overall result is similar to the navMap element tree, but doesn’t include nesting of <pageTarget> elements.

Example:

<navList>
  <navLabel>
    <text>List of Illustrations</text>
  </navLabel>
  <navTarget id="ill-1">
    <navLabel>
      <text>Portratit of Georg Gisze (Holbein)</text>
    </navLabel>
    <content src="content.html#ill1"/>
  </navTarget>
  <navTarget id="ill-2">
    <navLabel>
      <text>The adoration of the lamb (Van Eyck)</text>
    </navLabel>
    <content src="content.html#ill2"/>
  </navTarget>
</navList>

The navList element tree is not required by the ePub specification. It is used to allow for the creation of custom navigation lists. It is similar to the pageList element tree. It may not be used by all Readers, but is carried over into Version 3.x of the specification in a different form.

XHTML Navigation

Version 3.x of the ePub specification has moved away from using the NCX format and instead uses an XHTML document that is structured in a specific way to allow the creation of navigation documents, including both the Table of Contents and other sections that would have been handled by the pageList or navList elements under NCX. The relevant part of the spec to consult is here. It may be a good idea to look at example documents as well.

Note: all navigation documents should be included in the <manifest> section of the OPS file, and should have nav added to their list of properties. The navigation document that contains the TOC should be included in the <spine> section and other navigation documents may be added there as well.

Structuring the <head>

Your navigation document needs to still validate as HTML 5. This means you need, at minimum, a <head> with a <title> and a <meta> element containing the character set the document uses. You may include CSS or other additions to the head, but the Reader may ignore them in favor of whatever it uses to generate the TOC.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:epub="http://www.idpf.org/2007/ops">
  <head>
    <title>Robin Hood</title>
    <link href="../css/epub-serif.css" type="text/css" 
          rel="stylesheet"/>
    <link href="../css/headers.css" type="text/css" 
          rel="stylesheet"/>
    <meta charset="utf-8"/>
  </head>
  ...
</html>

The xmlns:epub attribute is important if your document adds some of the custom ePub markup used in its extension of HTML. Mostly this is custom vocabulary used to help markup various sections of the document. See this page for more details.

Structuring the <body>

Your goal is to wrap the TOC and any other navigation lists you are creating in separate <nav> elements with attributes that describe the type of list you are creating. These should all be wrapped in a root <section> or <div> tag and can include a <header> as well.

Example:

<head>
  ...
</head>
<body>
  <section epub:type="frontmatter toc">
    <header>
      <h1>Table of Contents</h1>
    </header>
    <nav xmlns:epub="http://www.idpf.org/2007/ops" epub:type="toc" 
         id="toc">
      <ol>
        <li id="toc-chapter-1">
          <a href="html/chapter-1.xhtml">
            Chapter I. How Robin Hood Became an Outlaw.
          </a>
        </li>
        <li id="toc-chapter-2">
          <a href="html/chapter-2.xhtml">
            Chapter II. How Robin Hood Met Little John.
          </a>
        </li>
        ...
      </ol>
    </nav>
    <nav xmlns:epub="http://www.idpf.org/2007/ops" 
         epub:type="landmarks" id="guide">
      <h2>Guide</h2>
      <ol>
        <li>
          <a href="#toc" epub:type="toc">Table of Contents</a>
        </li>
        <li>
          <a href="html/chapter-1.xhtml" epub:type="bodymatter">
            Begin Reading
          </a>
        </li>
      </ol>
    </nav>
  </section>
</body>

As you can see, each <nav> element contains an (optional) header and an ordered list of locations. Each <li> contains a single link to a location in the content with a description of that location inside of the link. epub:type attributes are added to each <section> element, each <nav> element, and to the occasional link. The values you should use for epub:type are described on this page.

You are only allowed to include one nav element of type toc in your ePub document. It corresponds to the <navMap> element used in NCX. Like the <navMap> you can nest the ordered lists to produce a more complete TOC.

You may also include a single (optional) nav element of type page-list. It corresponds to the <pageList> element of NCX. Ordered Lists contained in this element should not be nested and links should correspond (roughly) to page locations in a printed version of the ePub content.

You may also include a single (optional) nav element of type landmarks. It corresponds to the optional <guide> element from Version 2.x of OPF, and is used by some Readers to allow quick access to important sections of the content. In both Version 2.x and 3.x, this file may be used in the background by the Reader without ever being viewable by users, or it may just be ignored by the Reader.

Other <nav> elements can be included, just like they were with <navList> elements under NCX. These can be helpful, but any Reader apps are also allowed to ignore them in favor of their own navigation.

Looking Ahead

In conclusion, you should use the Navigation document type that corresponds to whatever version of ePub you are using. The XHTML used for Version 3.x is an improvement over the custom XML used in the NCX file, and should be preferred, but the XHTML still requires that you adhere to a specific structure if you want the Readers to actually use the file without any issues. The level of detail you include in your navigation document depends on your workflow and needs, but if you have time to include it, more detail is better in the long run.

In the next chapter, we will cover adding your HTML content. It will be the last of the “spec focused” chapters, and from there, we will examine different strategies for including technical content in your ePub document.

Previous

Next

Table of Contents