EPUB Navigation: Build a Reliable Table of Contents

EPUB navigation is reliable only when its visible labels, link destinations, chapter headings, and package order describe the same book. A file count cannot catch two links that point to one chapter, and a locally valid container cannot catch a misleading label. The practical audit follows every route from the contents text to the XHTML destination.

The retained STUDIO-262 package has five chapter XHTML files. Together with its generated structural pages, they form an eight-item spine. The EPUB contains a NAV document and an NCX document; reopening them produced five NAV list items and five NCX points. It contains zero image resources and zero image references, missing references are zero, and the local inspection returned valid=true. The exact inspected EPUB has SHA-256 e74d9851c925140855d66a31136c59ef2fb1158b9368eb128d71f070f5049c50. These are package observations. No one clicked every link in a named physical reader during this run.

Start with Five Intended Chapter Headings

List the five chapter sources in their intended reading order and copy each opening heading into a worksheet. Add the relative source path and a stable digest. This source list becomes the authority for both displayed labels and destinations. It prevents a familiar filename from being accepted after the wrong manuscript was selected.

The plan has five rows, not merely an expected count of five. If chapters have similar names, include a short sentinel from the opening paragraph. That small detail helps a reviewer distinguish a correct heading in the wrong file from the intended chapter.

Save the Book Order Before Generating Links

Select the five chapters and persist their order in the workspace. Reread the saved state before export. The package later reported eight spine items, which is consistent with the five body chapters and generated front or back matter in this fixture. Do not infer the source order from that total; resolve each spine item to its XHTML file.

A common failure occurs when a chapter is renamed after selection. The saved route may retain the older path or label. If a selected item no longer resolves, repair the workspace row and save it before regenerating. Do not wait for a reader to expose the stale link.

Pair Each NAV Label with Its XHTML Heading

Open the generated NAV document and read its five list items in order. For each anchor, capture the visible label and href. Resolve the path inside the EPUB, follow any fragment identifier, and compare the destination heading with the source worksheet. A complete row contains one source heading, one NAV label, one destination file, and one resolved heading.

Counting five anchors is only the first check. Two anchors may share an href, or a label may still use an older chapter title. Reject duplicate destinations, missing files, empty labels, and label-to-heading mismatches even when the overall count remains five.

Cross-Check the Five NCX Points

The same package includes toc.ncx with five navPoint elements. Read their labels and content sources, then compare them with the NAV routes. The order and resolved chapter set should agree. NCX is a compatibility cross-check; it does not replace the EPUB navigation document.

If NAV is correct but NCX points to an earlier chapter filename, preserve the output as a failed package. Fix the source selection or heading, generate a differently named EPUB, and compare both navigation forms again. Editing NCX inside the ZIP would break the link to the workspace and make the repair disappear on the next export.

The OPF for the retained package records the book title, Japanese language, and publisher. No image item is listed, no XHTML image reference appears, and all referenced resources are present. Store these facts beside, but not inside, the route table. Metadata completeness and navigation correctness are different acceptance decisions.

This separation matters during recovery. A navigation correction can accidentally change the book order or metadata if the wrong saved configuration is loaded. After every new export, repeat the OPF title, language, publisher, image count, missing count, and spine checks before accepting the repaired route set.

Diagnose the First Broken Link, Then Regenerate

Suppose the third NAV label is correct but its href reaches chapter two. Record that exact disagreement: row three, expected chapter three, actual chapter two. Preserve the EPUB digest and extracted documents. Return to the earliest incorrect layer—source order, saved selection, or heading—change only that input, and export to a new path.

Recovery is not complete when the third row alone passes. Resolve all five NAV links, all five NCX points, and all eight spine items in the new package. A new output may change unrelated routes, so previously accepted rows must be checked against the new digest.

Reserve Clicking and Visual Presentation for a Reader Test

ZIP inspection proves that links are syntactically present and resolve to packaged XHTML. It does not show how a specific reader labels its contents panel, whether it scrolls to a fragment, or whether a user can activate every row. A later interaction test should name the reader, version, device, and EPUB digest, then click routes one through five and record the displayed heading.

Retailer ingestion and identical layout across reading systems are also outside this package result. valid=true is a local structural value, not universal acceptance. Keeping the boundary explicit protects a useful route audit from becoming an unsupported display promise.

Close with Five Complete Route Rows

The STUDIO-262 receipt passes when the five intended chapters are in reading order, the spine has eight items, five NAV labels resolve to five distinct intended headings, and five NCX points describe the same set. It also records zero images, zero image references, zero missing resources, OPF metadata, the EPUB digest, and local valid=true.

Another operator should be able to start with the five-row worksheet, reopen the same package, and reach the same conclusion. Any empty label, duplicate destination, missing target, order disagreement, or unresolved row is a failure. Reader clicks remain an open field until someone performs that named-environment test.