📖 Chapter 90: HTML for E-Books (EPUB 3)

EPUB 3 Navigation Documents (nav.xhtml)

Constructing the Unified Nav Tree: Table of Contents, Structural Landmarks, and Physical Print Page Lists

LEARNING OBJECTIVES ⌵
  • Understand the role and structure of the EPUB 3 Navigation Document (nav.xhtml).
  • Construct multi-level, hierarchical Tables of Contents using <nav epub:type="toc"> and strict ordered lists (<ol>).
  • Configure the Landmarks navigation structure (<nav epub:type="landmarks">) to populate native e-reader jump drawers.
  • Implement a Page-List navigation (<nav epub:type="page-list">) to synchronize digital e-books with physical print page numbers.
🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation
🌐
1. Input
Directives & Tags
⚙️
2. Parse
Tokenizer & AST
🌳
3. Layout
Box Model & Flow
🎨
4. Render
GPU Paint & Composite
PHASE 1: INPUT & DIRECTIVES
Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

When a pilot steps into the cockpit of an airliner, they don't manually search through a physical filing cabinet to find route waypoints. Instead, they rely on a flight management computer that provides three distinct navigation systems:

  1. The Route Tree (TOC): The complete chronological path from takeoff, through waypoints, to destination.
  2. Emergency / Quick Landmarks: One-click quick jumps directly to the runway, nearest airport, or holding pattern.
  3. The Altitude / Distance Grid (Page List): A standardized coordinate grid that aligns the aircraft with other planes and ground controllers regardless of varying cabin instrument displays.
+-----------------------------------------------------------------------------------+
|                           EPUB 3 NAVIGATION DOCUMENT                              |
|                                                                                   |
|  [1. <nav epub:type="toc">]        <- Hierarchical Table of Contents (User Menu)  |
|  [2. <nav epub:type="landmarks">]  <- Native Quick Jumps (Cover, Start, Index)    |
|  [3. <nav epub:type="page-list">]  <- Physical Print Page Sync ("Go to Page 142") |
+-----------------------------------------------------------------------------------+

In EPUB 3, the Navigation Document (nav.xhtml) acts as this flight computer. Unlike legacy EPUB 2's rigid, machine-only XML file (toc.ncx), nav.xhtml is a dual-purpose XHTML5 document: it renders visually as a beautiful human-readable Table of Contents inside the book spine, while simultaneously exposing structured semantic markup that e-reader software parses to populate sidebar menus and touch drawers.

Technical Deep Dive & Specifications

The Three Pillars of nav.xhtml

An EPUB 3 Navigation Document consists of standard XHTML markup containing one or more <nav> elements tagged with specific epub:type attributes:

                  +-----------------------------------+
                  |        nav.xhtml Container        |
                  +-----------------------------------+
                                    |
        +---------------------------+---------------------------+
        |                           |                           |
        v                           v                           v
+-------------------+       +-------------------+       +-------------------+
|  epub:type="toc"  |       |epub:type="landmarks|      |epub:type="page-list|
|  (MANDATORY)      |       |  (OPTIONAL/REC)   |       |  (OPTIONAL)       |
|  Nested <ol> Tree |       |  Reader Jump Menu |       |  Print Page Sync  |
+-------------------+       +-------------------+       +-------------------+

1. The Table of Contents (epub:type="toc")

  • Mandatory: Exactly one <nav epub:type="toc"> must be present.
  • Strict <ol> Structure: The spec mandates that lists inside <nav> must use ordered lists (<ol>), not unordered lists (<ul>).
  • Unlinked Section Headings: If a category heading in the TOC does not link to an independent document, it must be wrapped in a <span> element, not bare text.
<nav epub:type="toc" role="doc-toc" id="toc">
  <h2>Table of Contents</h2>
  <ol>
    <li><a href="text/ch01.xhtml">Chapter 1: The Foundations</a>
      <ol>
        <li><a href="text/ch01.xhtml#sec1-1">1.1 What is Consensus?</a></li>
        <li><a href="text/ch01.xhtml#sec1-2">1.2 Network Topologies</a></li>
      </ol>
    </li>
    <li>
      <span>Part II: Advanced Systems</span> <!-- Unlinked structural grouping -->
      <ol>
        <li><a href="text/ch02.xhtml">Chapter 2: Vector Clocks</a></li>
      </ol>
    </li>
  </ol>
</nav>

2. Landmarks Navigation (epub:type="landmarks")

Reading systems (like Apple Books, Kobo, and Kindle) use the landmarks nav to build their native quick-jump drawers (e.g., "Jump to Cover", "Jump to Beginning of Book", "Jump to Table of Contents").

<nav epub:type="landmarks" hidden="">
  <h2>Guide &amp; Landmarks</h2>
  <ol>
    <li><a epub:type="cover" href="text/cover.xhtml">Cover</a></li>
    <li><a epub:type="toc" href="text/nav.xhtml">Table of Contents</a></li>
    <li><a epub:type="bodymatter" href="text/ch01.xhtml">Start of Reading</a></li>
    <li><a epub:type="glossary" href="text/glossary.xhtml">Glossary</a></li>
    <li><a epub:type="index" href="text/index.xhtml">Index</a></li>
  </ol>
</nav>

3. Page List Navigation (epub:type="page-list")

In academic classrooms and book clubs, readers using physical hardcovers and digital e-books need to stay on the same page. The page-list element correlates physical print page breaks with digital anchor points:

In text/ch01.xhtml:

<p>
  ...end of previous page text.
  <span id="page-42" epub:type="pagebreak" role="doc-pagebreak" aria-label="42" />
  Beginning of page 42 text...
</p>

In nav.xhtml:

<nav epub:type="page-list" role="doc-pagelist" hidden="">
  <h2>Page Navigation</h2>
  <ol>
    <li><a href="text/ch01.xhtml#page-41">41</a></li>
    <li><a href="text/ch01.xhtml#page-42">42</a></li>
    <li><a href="text/ch01.xhtml#page-43">43</a></li>
  </ol>
</nav>

The hidden Attribute Rule

Notice the hidden="" attribute on landmarks and page-list. When nav.xhtml is included in the reading spine, users seeing the page visually will only see the beautiful Table of Contents. The technical landmarks and long lists of thousands of print page numbers remain hidden visually, but are fully parsed by the e-reader's native UI menus and screen readers.

SYS: ACTIVE
HULL: 98%
CORE: STABLE
NET: ONLINE
HTML STARSHIP CODE TERMINAL example.html
root@STARSHIP-ALPHA:~/web-core# READY FOR COMPILATION █
LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C
INSPECTING DOM: VALID
TAGS: SCANNING...

💻 Interactive Code Playground

Starter Code: Production EPUB 3 Navigation Document (text/nav.xhtml)

Line-by-Line Code Breakdown

  • Line 11 (<nav epub:type="toc" role="doc-toc">): The mandatory Table of Contents root, paired with DPUB-ARIA role="doc-toc".
  • Line 13 (<ol class="toc-level-1">): The top-level ordered list. EPUB 3 strictly forbids <ul> here.
  • Line 19–25 (<ol class="toc-level-2">): Sub-level navigation nested directly within parent <li> items.
  • Line 37 (<nav epub:type="landmarks" hidden="">): Landmarks navigation tagged with hidden="". It remains invisible during visual reading but feeds the native e-reader app menus.
  • Line 40–44 (<a epub:type="cover" ...>): Tells reading systems where the cover, TOC, bodymatter start, and backmatter sections live.
  • Line 49 (<nav epub:type="page-list" ... hidden="">): Maps digital links directly to print page numbers. When a student enters "Jump to page 3", the e-reader navigates directly to ch01.xhtml#page-3.

Expected E-Reader UI Integration

SYS: ACTIVE
HULL: 98%
CORE: STABLE
NET: ONLINE
HTML STARSHIP CODE TERMINAL playground.html
root@STARSHIP-ALPHA:~/web-core# READY FOR COMPILATION █
LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C
INSPECTING DOM: VALID
TAGS: SCANNING...
+-------------------------------------------------------------+
| [≡ Menu]  Architecting Resilient Distributed Systems        |
+-------------------------------------------------------------+
| TABLE OF CONTENTS                                           |
|                                                             |
|   Book Cover                                                |
|   Preface & Author's Note                                   |
|   ▼ Chapter 1: The Consensus Paradox                        |
|       1.1 Defining Synchronization                          |
|       1.2 The CAP Theorem in Practice                       |
|   ▼ Chapter 2: Raft and Paxos Protocols                     |
|       2.1 Leader Election Dynamics                          |
|       2.2 Log Replication Guarantees                        |
|   Technical Glossary                                        |
|   References & Bibliography                                 |
|                                                             |
| ----------------------------------------------------------- |
| QUICK LANDMARKS: [Cover] [Start of Book] [TOC] [Glossary]   |
+-------------------------------------------------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Complete Tri-Navigation Document

Instructions:

  1. Build a valid nav.xhtml file for a 2-chapter publication.
  2. The Table of Contents (epub:type="toc") must have a primary title, Chapter 1, Chapter 2, and an Appendix.
  3. Add a hidden <nav epub:type="landmarks"> linking to cover.xhtml (as cover) and chapter1.xhtml (as bodymatter).
  4. Add a hidden <nav epub:type="page-list"> linking print pages 1, 2, and 3.

🏁 Starter Code Sandbox

SYS: ACTIVE
HULL: 98%
CORE: STABLE
NET: ONLINE
STARTER CODE SANDBOX exercise.html
root@STARSHIP-ALPHA:~/web-core# READY FOR COMPILATION █
LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C
INSPECTING DOM: VALID
TAGS: SCANNING...

⚠️ Common Pitfalls

  1. Using <ul> inside Navigation Elements: EPUB 3 strictly mandates <ol> for navigation trees. Using <ul> will immediately fail epubcheck validation.
  2. Omitting Required Headings inside <nav>: Every <nav> element must contain a heading (<h1> through <h6>) to provide accessible landmark context to screen readers.
  3. Raw Text in <li> Elements: Writing <li>Part I: Core Concepts</li> without wrapping the unlinked text in a <span> tag violates the navigation specification.

💡 Pro Tips

  1. Style for Dual Visibility: Remember that nav.xhtml can be displayed directly in the reading flow (if placed in the spine) or rendered via the e-reader's modal interface. Use clean CSS resets to remove default browser numbers from <ol> (list-style-type: none;) for a polished layout.
  2. Combine with ARIA Labels: Add aria-label="Table of Contents" and role="doc-toc" to ensure screen readers announce navigation elements accurately across all devices.

📌 Key Takeaways

  • The Navigation Document (nav.xhtml) replaces EPUB 2's toc.ncx with modern, human-readable XHTML5 markup.
  • Every EPUB 3 publication must include exactly one <nav epub:type="toc"> containing strictly ordered lists (<ol>).
  • Non-hyperlinked grouping items in the TOC must be wrapped in <span> tags rather than raw text.
  • The <nav epub:type="landmarks"> element powers native e-reader quick-jump menus (Cover, Start of Reading, TOC).
  • The <nav epub:type="page-list"> element bridges digital reflowable text with physical hardcover page numbers.
  • Secondary nav elements (landmarks, page-list) should be declared with the hidden="" attribute.
  • --
⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 1 / 3

Which HTML list element is MANDATORY inside EPUB 3 <nav> containers?

Question 1 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 2 / 3

How should a non-hyperlinked grouping header (e.g., "Part I: Foundations") be structured inside an EPUB 3 TOC?

Question 2 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP
3x
STREAK!
BONUS ACTIVE
COMBO
? Question 3 / 3

Why is the hidden="" attribute applied to <nav epub:type="landmarks"> in nav.xhtml?

Question 3 / 3 Topic: HTML Fundamentals
00:45 REMAINING
XP REWARD
+250 XP