Fix EPUB contents links and missing navigation entries

1. Identify which table of contents is wrong

A visible contents page is part of the book’s reading pages. The navigation menu is the chapter list supplied to the reading app. EPUB 3 uses a navigation document; older EPUBs may use an NCX file. A book can show a contents page while the reader’s chapter menu is incomplete, or the menu can work while a link in the visible page is broken.

Open the exact EPUB you intend to publish or share. Test both the visible contents page and the reader’s chapter menu. Note the entry label, the expected chapter and what happens when you select it. If only a publishing-platform preview behaves differently, compare it with a local reader before assuming the EPUB itself is wrong.

• A click goes nowhere: the referenced file or anchor may be missing.
• An entry jumps to the wrong chapter: its destination may exist but be incorrect. A valid link is not proof of the right destination.
• A chapter is absent from the menu: inspect the headings and navigation entries. The chapter text may still be present.
• Nested chapters look wrong: check heading levels separately from link destinations.

2. Inspect the EPUB before applying changes

Upload the EPUB in the ChapterTidy workspace, or use “Try a sample manuscript” first. Review the chapter outline alongside the issue list. The current EPUB parser checks internal file and anchor references, missing navigation, navigation mismatches and skipped heading levels.

A suggested link repair is available when a broken link’s label matches one unique heading with an anchor. If the match is ambiguous, do not guess. Inspect the manuscript and select the intended target where the issue offers a target selector. ChapterTidy does not invent missing chapter text or guarantee that every semantically incorrect link will be detected.

3. Select the repair and check the proposed structure

Select only the repairs that fit your manuscript. Compare the source and proposal views. Review heading changes carefully: a section nested under a chapter should not become a new top-level chapter just to make the outline look tidy. Save the repair plan when the selected changes are correct.

For missing or mismatched navigation, review the headings before accepting a navigation creation or rebuild. A navigation list based on incorrect headings will still be the wrong list for your book. Leave intentional structures unchanged and use the lock control for content you want to protect.

A reproducible example in the sample manuscript

The included “The Quiet Hours” EPUB deliberately contains a contents link labelled “2. The quiet hours” that points to book.xhtml#missing. The matching chapter heading has the anchor quiet. The parser therefore offers book.xhtml#quiet as the replacement. The sample also exposes a navigation mismatch and a skipped heading level.

This is a test fixture, not a customer success story or a promise about other books. You can try it without uploading your own manuscript, compare the proposed changes and inspect the downloaded EPUB.

4. Verify the exported file, not just the workspace

Generate the EPUB and review the export report. Check the reference and EPUB validation results, text and image preservation checks, and any item marked for review. A failed required check can block download; a review draft is not the same as a publication-ready file.

Open the downloaded EPUB in your target reading app. Click every contents entry in both navigation views, confirm the chapter destination and nesting, and check the beginning and end of chapters. For Kindle publishing, use Kindle Previewer and the current KDP instructions as an additional step. No ChapterTidy report guarantees KDP acceptance.

If EPUBCheck reports a failure, keep the complete message and its internal file location before changing the book. A validation code alone does not identify the safest repair; use the report-reading guide to separate message severity, source locations and platform rules.

A working table of contents does not check the journey through a footnote. If your book includes notes, test each reference, the full note and its return link separately; an existing target can still be the wrong destination.

• Does each entry land on the intended heading?
• Are chapter order and nesting correct?
• Are the opening, images, notes and final paragraphs still present?
• Does the file behave correctly at a narrow width and a larger font size?

• If only KDP reports a problem, use the file and previewer checklist
• Read EPUBCheck errors and choose a safe next step
• Check footnote targets and return links

Should I repair a nav document or add an NCX file?

Do not add an NCX file merely because a forum answer mentions one. EPUB 3 uses its navigation document; EPUB 2 uses NCX. First identify the EPUB version and inspect the navigation it actually contains. A visible contents page alone does not tell you whether the reader navigation is present or correct.

Use ChapterTidy when you want to review detected heading, navigation and internal-link issues before applying supported repairs. If you need to inspect or edit the underlying XHTML, identifiers or package structure directly, an EPUB editor such as Calibre or Sigil may be a better next step. Manual editing still needs validation and a check of the exported file in a reader.

• Choose between repairing, reformatting and converting a manuscript

What this workflow cannot establish

EPUBCheck tests conformance to the EPUB specification. Reader testing checks how a particular app displays and navigates a book. Neither one establishes the other, and neither guarantees a publishing platform will approve your file.

ChapterTidy processes uploaded files on its server. Files are retained for 24 hours by default and can be deleted from the workspace. Use a manuscript you are permitted to upload. Complex layouts and unusual book structures need careful manual review.