Create an NCX File

Guest article by Araby Greene, webbishbooks.com

Navigation Control file for XML applications

After reading some of the comments on Kindle-related discussion lists, including Amazon's own DTP List, you might conclude that NCX stands for "Not Clearly eXplained" because of confusion about Amazon's requirement that Kindle book uploads must include an NCX file. NCX stands for "Navigation Control file for XML applications". The NCX file itself is an XML (eXtensible Markup Language) file with an extension of ".ncx" and a standard format that outlines the hierarchical structure of an eBook. For more information about the role of the NCX file with eBooks, see Clarify NCX Reading System Requirements by the Daisy Consortium.
"Hierarchical structure" refers to the relative "level" of items in the book. A book in which all segments are on the same level, with none higher or lower, has 1 level. Some books have Parts that contain Chapters. The Chapters are on a lower level than Parts. If you outlined the book, Chapters would be indented ("nested") below Parts. Such a book has 2 levels. If it were in ePub format, its NCX file could specify a "depth" of 2 levels, and list Chapter "navPoint" tags nested inside Part "navPoint" tags.

The NCX file for a Kindle book is written as though the book has 1 level, even if it has more, with Parts and Chapters listed in the order in which they appear, one after another, not nested as they would be in an outline.

What does the NCX file do for readers of your eBook?

The NCX file aids navigation, but in a different manner than the Table of Contents. It contains a collection of navPoint tags, with one navPoint for each "navigational waypoint" in the book. Taken together, the navPoints create a navigation map, and are wrapped in a navMap tag. Each navPoint creates a link that goes to a bookmark you previously created in your book's HTML file(s).
The navMap for a long book might include navPoints for Copyright, Table of Contents, Acknowlegements, Preface, List of Illustrations, Parts, Chapters, Epilogue, and so on. The navMap for a short book might have navPoints for only the Introduction and several Chapters.
In a Digital Talking Book, each navPoint in the NCX can be linked through a SMIL (Synchronized Multimedia Integration Language) file to the corresponding location in audio and text files. In this type of book, navPoint content links would go to locations in a .smil file instead of a .html file.
You can observe how an NCX file works in Kindle Previewer, from which the following screenshots were taken.


Kindle Previewer displays icons for the Table of Contents and NCX View:
Kindle Previewer top menu
Double-click an item in the NCX list to go to that place in the book:
Screenshot: NCX View
The link to THE WOOING OF BECFOLA lands where the story begins:
Screenshot: Chapter heading
navPoints in a Kindle book appear as tick marks in the Progress Bar:
Screenshot: Kindle Progress Bar
The tick marks provide cues about the location of book segments along the Progress Bar and their relative size. The Bar also indicates "percentage read" and amusing, if not easily interpreted, statistics about the number of locations in the book and your current location.
The Table of Contents is another way to navigate through a book in Kindle Previewer. For titles with many sections or chapters, the TOC may be more spread out than the NCX View, and require much page-turning to reach a desired section.
Table of Contents view:
Screenshot: Kindle Previewer TOC
The HTML code for the Table of Contents shown above is:

<h2>Contents</h2>
<div class="center">
<p height="30"><a href="book.html#preface">Preface</a></p>
<p height="30"><a href="book.html#S1"><b>THE STORY OF TUAN MAC CAIRILL</b> </a></p>
<p><a href="book.html#S1-CH1">CHAPTER I </a></p>
<p><a href="book.html#S1-CH2">CHAPTER II </a></p>
<p><a href="book.html#S1-CH3">CHAPTER III </a></p>

Where is the NCX file?

The NCX file is always a separate file in the eBook's folder, along with the required OPF (Open Packaging Format) file. There are two places in the .opf file where the NCX file must be referenced:
  • as an item in the manifest tag, which lists files that comprise the eBook.
  • as an attribute of the spine tag, which lists items in their reading order.
An eBook should also have an HTML Table of Contents, which can be included in the book's HTML file or exist as a separate toc.html file.
The OPF file contains a package element with child elements for metadata, manifest, spine, and guide. The metadata element includes information describing the book; the manifest, a list of files in the package; the spine, a list of (x)html documents in reading order; the guide, an optional list of structural components used by reader software, such as Table of Contents, Introduction, start location, Glossary, and other types of information.

What's in the NCX file?

The bulk of the NCX file is the collection of navPoint tags used to create Kindle Previewer's NCX View and Progress Bar tick marks. Each navPoint tag includes two child tags: navLabel and Content. The navLabel is title text; the Content tag, a link to the corresponding anchor tag in the book's HTML file or files. You may create the anchor tags as you write the book, or afterwards, depending on your workflow. Either way, they must be present before you create your HTML Table of Contents in Word or manually. After you make the toc.html file, you can use it as a convenient list of "bookmark anchors" (links with names) when constructing the NCX file.
Don't drop your anchors! Your eBook's content files must contain a named bookmark anchor for each entry in the TOC file and each navPoint in the NCX file navMap. An "anchor" is simply an HTML hyperlink, or <a> tag. When an anchor has a name, you can link directly to its specific location inside an HTML document. For example, let's say we create the bookmark anchor <a name="Chap2"/> just above the beginning of Chapter 2, in a file named "book.html". A link that goes directly to this bookmark's location would be: <a href="book.html#Chap2">. In links, the anchor name is preceded by the pound(#) sign.
Two important things to understand about the TOC and NCX file:
  1. Neither the toc.html nor the .ncx file must contain a complete list of every anchor present in the book file. Unused anchor tags do no harm, but they obviously have to exist in order to link to them. The NCX file may have more or fewer items than the TOC. The NCX file might be a simplified list of contents, while the TOC could be a longer, nested list of Parts and Chapters, plus special pages, such as an Introduction or Bibliography. It's up to you.
     
  2. The Kindle does not support nested navPoints in the NCX file. Remember that navPoints are the basis of tick marks in the Kindle's Progress Bar. The flat display of tick marks doesn't play well with nested navPoints. The NCX file can list Parts, Chapters, and even Sub-chapters in navigation order, but the list has to be flat, not nested. That is, each item must be a complete navPoint, without other navPoints inside of it. The TOC can serve as the "visual" outline of your book. Perhaps the next generation of Kindles will have nested navigation menus similar to those in ePub readers!
NCX File structure
The NCX XML file has a standard structure, or DTD, that must be slavishly followed, in a "well-formed" file with all tags in their proper place. XML is unforgiving of syntax errors, but the rules for a basic NCX file are easy to follow. The easiest approach is to start with a working example for reference, create a skeleton file, and add your own content to it. Space out your draft file so you can see what you're doing, and when finished, remove extra line breaks.
The basic structure of the NCX file, in pseudocode is:
<?xml version="1.0" encoding="WhateverYouUse"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN" 
  "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/"  
  version="2005-1" xml:lang="en-US">
<head>
  <meta name="dtb:uid" content/>
  <meta name="dtb:depth" content/>
  <meta name="dtb:totalPageCount" content/>
  <meta name="dtb:maxPageNumber" content/>
</head>
<docTitle>Text</docTitle>
<docAuthor>Text</docTitle>
<navMap>
  <navPoint id="whatever" playOrder="n">
    <navLabel><text>TheTitle</text></navLabel>
    <content src="file.html#namedAnchor" />
  </navPoint>
  <navPoint id="whatever" playOrder="n">
    <navLabel><text>The Title</text></navLabel>
    <content src="file.html#namedAnchor" />  
  </navPoint>
  ...
</navMap>
</ncx>
The actual code in my sample book's toc.ncx file is shown below. Most toc.ncx files designate the first page of text (Preface, Introduction, Chapter One, etc.) as the starting point, skipping the "front matter". That's up to you.
Each story in the book is preceded by a simple anchor in the format: <a name="Snumber"/>. For example, the anchor for the third story in the book is <a name="S3"/>. Chapter anchors, if added, would look like <a name="S3-CH2"/>, a bookmark for the third story, second chapter.
Each navPoint content tag has a src attribute that points to the book's html file+anchor. For example: book.html#S3
<?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">
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/"  
  version="2005-1" xml:lang="en-US">
<head>
<meta name="dtb:uid" content="uid"/>
<meta name="dtb:depth" content="1"/>
<meta name="dtb:totalPageCount" content="0"/>
<meta name="dtb:maxPageNumber" content="0"/>
</head>
<docTitle><text>Irish Fairy Tales</text></docTitle>
<docAuthor><text>Stephens, James</text></docAuthor>
<navMap>
<navPoint id="titlepage" playOrder="1">
<navLabel><text>Title Page</text></navLabel>
<content src="book.html#start"/>
</navPoint> 
<navPoint id="preface" playOrder="2">
<navlabel><text>Preface</text></navLabel>
<content src="book.html#preface"/>
</navPoint>
<navPoint id="toc" playOrder="3">
<navlabel><text>Table of Contents</text></navLabel>
<content src="toc.html"/>
</navPoint>
<navPoint id="navpoint-1" playOrder="4">
<navLabel><text>THE STORY OF TUAN MAC CAIRILL</text></navLabel>
<content src="book.html#S1"/>
</navPoint>
<navPoint id="navpoint-2" playOrder="5">
<navLabel><text>THE BOYHOOD OF FIONN</text></navLabel>
<content src="book.html#S2"/>
</navPoint>
<navPoint id="navpoint-3" playOrder="6">
<navLabel><text>THE BIRTH OF BRAN</text></navLabel>
<content src="book.html#S3"/>
</navPoint>
<navPoint id="navpoint-4" playOrder="7">
<navLabel><text>OISIN&#39;S MOTHER</text></navLabel>
<content src="book.html#S4"/>
</navPoint>
<navPoint id="navpoint-5" playOrder="8">
<navLabel><text>THE WOOING OF BECFOLA</text></navLabel>
<content src="book.html#S5"/>
</navPoint>
<navPoint id="navpoint-6" playOrder="9">
<navLabel><text>THE LITTLE BRAWL AT ALLEN</text></navLabel>
<content src="book.html#S6"/>
</navPoint>
<navPoint id="navpoint-7" playOrder="10">
<navLabel><text>THE CARL OF THE DRAB COAT</text></navLabel>
<content src="book.html#S7"/>
</navPoint>
<navPoint id="navpoint-8" playOrder="11">
<navLabel><text>THE ENCHANTED CAVE OF CESH CORRAN</text></navLabel>
<content src="book.html#S8"/>
</navPoint>
<navPoint id="navpoint-9" playOrder="12">
<navLabel><text>BECUMA OF THE WHITE SKIN</text></navLabel>
<content src="book.html#S9"/>
</navPoint>
<navPoint id="navpoint-10" playOrder="13">
<navLabel><text>MONGAN&#39;S FRENZY</text></navLabel>
<content src="book.html#S10"/>
</navPoint> 
</navMap>
</ncx>
Make a skeleton template
To speed things up, create your own NCX file template in a text editor. Add the standard code at the top, and below that, add the <navMap> tag. Make a dummy navPoint, something like this:
<navPoint id="navpoint-" playOrder="">
<navLabel><text></text></navLabel>
<content src=".html#"/>
</navPoint>
Paste as many of the dummy navPoints as you think you'll need and number them. Then copy and paste the navPoint titles and anchor names from your HTML TOC.
Remember that the TOC and NCX files do not have to contain exactly the same amount of detail. Also, navPoint IDs can be anything you want. A simple numbering system will do fine for the book Parts, Sections, and Chapters. The book's starting point should have an anchor named "start".
In XML an id attribute must not start with a number, even though it may contain numbers. The first character can be a letter, underscore or colon.

Add the NCX file to MobiPocket Creator

After you finish adding your publication files to MobiPocket Creator, and have placed the NCX file in your eBook's project folder, make sure you click the Save button or press CTRL-S before proceeding further.
Note that MPC creates an OPF file the first time you Save your project, and then updates it each time you Save. You may manually view and edit the OPF file at any time after it is first created.
Before clicking the Build button, go to your publications/book folder and open the .opf file in a text editor. Add the required NCX item to the <manifest>. Replace the <spine/> tag with a new one that includes a reference to the .ncx file. Save the .opf file. Then go back to MobiPocketCreator and click Build. The pasted addition to my sample book's .opf file is shown below:
<?xml version="1.0" encoding="utf-8"?>
<package unique-identifier="uid"><metadata><dc-metadata xmlns:dc="http://purl.org/metadata/dublin_core" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/"><dc:Title>Irish Fairy Tales</dc:Title><dc:Language>en-us</dc:Language><dc:Identifier id="uid">5CD9B792AC</dc:Identifier><dc:Creator>Stephens, James</dc:Creator><dc:Publisher>Greene Village</dc:Publisher><dc:Subject BASICCode="FIC007000">Tales &amp; Fables</dc:Subject><dc:Description>Tales from Irish folklore retold by James Stephens. First published in 1920. Stephens (February 9, 1882-December 26, 1950) was also a notable Irish poet and author. His popular novel, The Crock of Gold, is loosely based on fairy tales.</dc:Description><dc:Date>05/23/2010</dc:Date></dc-metadata><x-metadata><output encoding="utf-8" content-type="text/x-oeb1-document"></output><EmbeddedCover>iftCover.jpg</EmbeddedCover><SRP Currency="USD">.99</SRP></x-metadata></metadata><manifest><item id="item1" media-type="text/x-oeb1-document" href="toc.html"></item><item id="item2" media-type="text/x-oeb1-document" href="book.html"></item><item id="ncx" media-type="application/x-dtbncx+xml" href="toc.ncx"></item></manifest><spine toc="ncx"><itemref idref="item1"/><itemref idref="item2"/></spine><tours></tours><guide><reference type="toc" title="Table of Contents" href="toc.html"></reference><reference type="start" title="Start" href="book.html%23start"></reference></guide></package>
Look at the .prc file in Kindle Previewer to make sure "tick marks" have been added to the Progress Bar, and that the NCX View is present and correct. While you're at it, check the Table of Contents to make sure it looks the way you want.
If the tick marks are not present in the progress bar, go back and check your .ncx file to make sure all tags are closed. The file will be easier to proofread if you add line breaks while you review it.

KindleGen

If you use KindleGen to create a .mobi version of your book, note that the KindleGen OPF differs significantly from the MPC-generated OPF file, particularly in how metadata is listed. Save a backup of your MPC .opf file and revise a copy of it with KindleGen formatting before attempting to use the kindlegen command. The KindleGen Sample folder offers examples of both OPF and NCX files.

Creating an NCX file is not so difficult! Good luck with your Kindle projects!