# Add useful section navigation to a long HTML document

Canonical: https://githtml.com/guides/table-of-contents-for-long-html
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Create a short list of links to meaningful heading IDs near the beginning of the document. Use stable, descriptive fragments and keep the visible labels aligned with the destination headings. A plain HTML table of contents works without JavaScript and is often enough for a substantial report on iPhone.

## Choose navigation by reader task

A useful table of contents is not a dump of every heading. Include the sections readers are likely to revisit: setup, findings, decision, limitations, or rollback instructions. Deeply nested lists make the opening screen feel like another document to read. For a long technical report, a handful of major destinations is usually a better starting point.

Imagine a reader returning during a meeting to answer one question. Could they find the constraints or the next steps from the link labels alone? Replace decorative headings such as The journey with descriptive ones such as Migration constraints when the purpose is reference. Navigation should expose the document's argument without requiring the reader to memorize its layout.

## Make fragment identifiers durable

Attach IDs to the corresponding headings or sections. Keep each ID unique within the file and avoid changing it just because you refine the visible wording. A fragment such as deployment-risks is easier to maintain than an automatically assigned number that changes whenever a section is inserted. Existing links can otherwise land at the wrong conceptual location.

For an exported document, check the final HTML rather than the source notation. Some converters alter punctuation or deduplicate repeated headings in unexpected ways. Follow every contents link in the delivered artifact. If the document includes a fixed header, check whether the target heading becomes hidden underneath it; simpler static headers avoid this problem entirely.

## Offer enough context at the destination

A reader arriving through a section link may skip the introduction. Begin important sections with a sentence that identifies their scope. Avoid opening with only This is why or As mentioned earlier. A destination should make sense independently while still belonging to the larger report.

1. Check for duplicate IDs after merging exported sections.
2. Keep navigation labels concise enough to wrap cleanly on a phone.
3. Use return links sparingly; a repeated back-to-top link after every paragraph adds clutter.

````html
<nav aria-label="Document sections">
  <a href="#constraints">Constraints</a>
  <a href="#decision">Decision</a>
</nav>
<h2 id="constraints">Migration constraints</h2>
<p>The migration must preserve existing document URLs.</p>
<h2 id="decision">Decision</h2>
````

## Sources and further reading

- [MDN: the anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a)

## Related guides

- [Read a repository HTML document comfortably on iPhone](https://githtml.com/guides/read-repository-html-on-iphone)
- [Build a single-file HTML document that travels well](https://githtml.com/guides/portable-single-file-html-document)
- [Set a mobile viewport for an HTML report](https://githtml.com/guides/mobile-viewport-for-html-reports)
- [Format code samples for reading on an iPhone](https://githtml.com/guides/code-blocks-for-iphone-reading)

Editorial approach: https://githtml.com/guides/about