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).
Navigation Center eXtended (NCX)
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 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> . . . </head>
A wrapper element for all of the meta data in this file.
<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 <firstname.lastname@example.org>"/> <meta name="dtb:totalPageCount" content="0"/> <meta name="dtb:maxPageNumber" content="0"/> </head>
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> <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> <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.
<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.
<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> <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>
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
<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>
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.
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.