Marking Up Page Numbers in the EPUB NCX

Below is an example <pageList> markup (that is valid per the NCX DTD) which can be used to mark up page numbers within ePub documents.

Note that <pageList> must be placed right after the required <navMap>, and must occur before the first optional <navList>. There may be one and only one <pageList> (but there can be any number of <navList> — of course, there can only be one <navMap>).

<pageList id="page-mapping">

  <navLabel><text>Paper Edition Page Mapping</text></navLabel>

  <pageTarget id="page-iii" value="3" type="front" playOrder="82">
    <navLabel><text>Page iii</text></navLabel>
    <content src="frontmatter.html#pageiii"/>

  <!-- ... -->

  <pageTarget id="page-105" value="105" type="normal" playOrder="192">
    <navLabel><text>Page 105</text></navLabel>
    <content src="chap5.html#page105"/>



1. Currently there is an error in epubcheck 1.0.3 which says <pageList> must include both the id and class attributes, while they should be optional. Hopefully that bug will get fixed. The above markup includes the optional id (generally a good idea), but not the class so it will not validate to 1.0.3.

2. On <pageTarget>, the type attribute is required and takes one of three values: front, normal, or special. I interpret front to mean front-matter, normal to mean ordinary body matter, and special to mean back matter or some other special section which is not front or body matter.

3. On <pageTarget>, the value attribute is optional and I interpret it to contain an integer number expressing the page value associated with the given type. a type:value pair must be unique in the NCX, which cannot be checked by XML validation. [Note that playOrder is required.]

4. Based on figuring out how this would work in the authoring and reading system environments, it is highly recommended that the target fragment identifier for the “new page” NOT point to an existing id associated with some document structure, but should point to an id specifically associated with the beginning of a new page.

This means adding id to either an existing element marking the beginning of a new page which does not already have an id, or adding a <span class=”newpage” id=”pagexxx”></span> or <div class=”newpage” id=”pagexxx”></div> as needed to pinpoint the location of the start of a new page and its value.

Note that in my example above, I added special id values of pageiii and page105 to the content, and not used id values associated with some document structure (such as header, paragraph, etc.)

[Editors Note: Thanks to Jon Noring for writing the above article.

I would like to add that although the above method IS valid against the NCX DTD, marking up pages numbers in this way has not yet been officially approved by the IDPF. It must also be noted that there are yet no reading systems that would utilize this information.

This method is now being discussed in the EPUB Working Group. If it does become part of the official specification, then it should not be a burden on reading system developers since the syntax for <navList> and <pageList> is the same as that for <navMap>.]

If you liked this post, say thanks by sharing it.