THE GITHTML FIELD GUIDE
Fix section links that do not reach the right heading
Match each fragment link to one unique ID in the delivered HTML. Check the actual export for renamed or duplicated identifiers, then inspect whether a fixed header hides the target after navigation. Keep IDs stable when editing headings and prefer same-document fragment links for navigation within a portable reading artifact.
Compare the link and destination literally
A link to #installation needs a destination with id="installation" in the same document. Similar wording in a heading is not sufficient. Export tools may normalize punctuation, add suffixes, or generate different identifiers after a heading is renamed. Inspect the final file rather than assuming that a source document's heading syntax maps to the expected fragment.
Duplicate IDs can appear when chapters, templates, or reusable sections are combined. A browser may navigate to an earlier matching element instead of the intended section. Search all occurrences of the target ID and assign a unique identifier to each destination. Use descriptive names that reflect the topic rather than position-dependent numbers whenever practical.
Distinguish missing targets from hidden targets
Sometimes navigation succeeds but the heading lands underneath a fixed banner. The reader sees nearby text and assumes the link is wrong. Temporarily remove the fixed positioning during local inspection to determine whether it causes the problem. A reading document may be better served by a normal-flow header than a permanent overlay.
A base element can also change the resolution of links. Likewise, an exported link that includes a full website path may leave the artifact instead of moving within it. For a portable single document, keep internal navigation explicit and simple. Do not replace a basic fragment link with JavaScript scrolling unless there is a clear requirement and an accessible fallback.
Create a repeatable navigation check
After repairing a link, check its neighbors as well. A generator setting may have affected every heading, not just the first broken example. Include navigation verification in the export review so future title edits do not silently break shared links. If old fragments have already been distributed, consider preserving compatible destinations where that can be done cleanly.
- Copy the fragment from the link and find the exact ID in the exported HTML.
- Confirm that the ID occurs only once.
- Check whether the link accidentally includes a different document path.
- Inspect any base element and fixed-position header.
- Follow links near the beginning, middle, and end.
- Keep the target's introductory sentence understandable for readers arriving without the preceding sections.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.