A WordPress table of contents should help readers reach useful sections, not merely repeat every heading. Choose a short set of meaningful destinations, give those headings stable unique anchors, link to them and test the final page with its real mobile header. A jump that hides the heading behind a sticky bar is not finished navigation.
This guide covers a manual baseline, when an existing automated component may be preferable, and a practical acceptance checklist. It does not require a new plugin or promise extra Google result features.
When a table of contents is worth adding
Use it when the page contains several distinct tasks or questions and readers may arrive needing only one part. A long troubleshooting guide is a good candidate. A short answer with two brief sections may not need another navigation block before the useful content.
Do not apply an arbitrary word threshold as if it were a search requirement. Evaluate whether the map saves effort. If the list is nearly as long as the article, it may simply create another obstacle.
The on-page SEO checklist covers the broader page structure. Here the task is narrower: a reliable route to the right place within one page.
Sources and scope
WordPress's page-jump documentation, reviewed October 18, 2026, describes setting an HTML Anchor on a Heading block through Advanced settings, then linking to it with #anchor-name. Anchors must be unique within the document and are case-sensitive; use a simple letter-led identifier without spaces. A full page URL plus its fragment can link to another page's section.
The section-selection framework, maintenance record and test cases below are editorial recommendations. No theme, plugin or device benchmark was performed for this guide. The visible section links near the beginning demonstrate the same principle without claiming that every site's styling will behave identically.
Step 1: choose sections that reflect reader tasks
List the questions readers are likely to want independently. For a setup guide, they might need prerequisites, configuration, testing and troubleshooting. For a comparison, they may need the quick decision table and detailed option evaluations.
Use descriptive labels rather than “Section 1” or a string of repeated keywords. Someone scanning the table should understand the destination before clicking. The label does not have to reproduce a long heading word for word, but it should preserve its meaning.
| Candidate | Include when | Consider leaving out when |
|---|---|---|
| Main procedure | It answers a distinct practical task | It is only a tiny paragraph beneath another clear section |
| Prerequisites | Readers need to check eligibility or required inputs | There are no meaningful prerequisites |
| Decision table | It helps readers choose a path | It repeats the introduction without adding a decision |
| Troubleshooting | Several specific failure states are covered | It contains only generic reassurance |
| Every H3 | The guide genuinely needs that detailed navigation | It creates an overwhelming list on mobile |
This selection process can reveal a deeper structure problem. If the table needs twenty nearly identical labels, consolidate the content before styling its navigation.
Step 2: assign stable, readable anchors
In the block editor, select the intended Heading block, open its Advanced setting and enter the approved HTML anchor. Then create a link using the corresponding fragment with a leading hash. Follow the current official instructions if the editor layout differs.
Choose an identifier tied to the section's durable purpose, such as test-navigation, rather than a date, paragraph number or overly long sentence. Keep a small mapping of labels to anchors when several editors maintain the page.
Do not reuse the same identifier for two headings. Repeated labels such as “Troubleshooting” in several sections need distinct destinations if both are linked. A link that lands on the wrong repeated section can be difficult to notice during a quick visual review.
A compact illustrative HTML pair
This example explains the relationship. It is not a request to paste duplicate markup beside a component already producing the same navigation.
<a href="#test-navigation">Test the navigation</a>
<h2 id="test-navigation">Test the navigation</h2>The code example is displayed as text; this article's actual section uses that identifier. On another page, ensure the identifier is unique there and the label accurately describes its destination.
Step 3: use one navigation owner
If the theme, editor or existing integration already provides a table of contents, inspect its behavior before adding a second one. Decide whether it generates anchors, how it updates after heading edits and whether it allows a sensible heading depth.
A manual list offers direct control for a small number of maintained guides. An existing automated component may reduce repeated editing across a larger publication. Neither is automatically better: compare maintenance needs, output and usability on representative pages.
Do not install an entire additional SEO suite solely for this feature. If a new component is genuinely required, review its broader operational and maintenance implications separately.
Step 4: check sticky-header overlap
Open the published page logged out, click a section link and see where the heading lands. Test with the actual header, announcement bar and mobile menu behavior. An administrator toolbar can change what an editor sees, so do not use the logged-in view as the only test.
If the heading is covered, ask the implementation owner to address the offset in the site's supported styling. A developer may evaluate scroll-margin-top, documented in the MDN CSS reference, as part of the solution. The value and selector must suit the actual layout.
/* Illustrative starting point, not a universal header measurement */
.article-content h2[id],
.article-content h3[id] {
scroll-margin-top: 6rem;
}Replace the example selector with the real content wrapper and measure the relevant header behavior. Do not add a large top margin to every heading merely to make one jump look right; that can create unwanted whitespace throughout the article.
After any CSS adjustment, retest ordinary reading, not just anchor clicks. A fix that exposes the heading but breaks the layout is not complete.
Step 5: run a short functional test
Click each entry and confirm the destination heading is correct and visible. Open a direct link containing the fragment in a fresh tab. Test the final cached page, not only an editor preview.
Use keyboard navigation as well as a pointer. Check whether links can be reached and activated, focus remains understandable and the table does not depend on a hover-only interaction. If a collapsible component is used, test opening and closing it rather than assuming the visual icon communicates its state.
Review a narrow mobile viewport and enlarged text. Labels should wrap sensibly without horizontal scrolling or tiny tap targets. Keep important content reachable without requiring a complicated animation.
| Test | Expected result |
|---|---|
| Every section link | Correct destination, no duplicate identifier confusion |
| Direct fragment URL | Intended section remains reachable on initial load |
| Sticky header | Destination heading stays visible |
| Keyboard use | Links and any controls can be operated clearly |
| Mobile and enlarged text | Readable labels without overflow |
| Logged-out cached page | Current links and anchors are delivered |
| Heading revision | Existing links remain valid or are deliberately updated |
Worked example: a long client-onboarding guide
Imagine a Pakistani agency has a detailed onboarding article. Readers want to jump to required access, baseline evidence or the kickoff agenda. The existing table lists every subheading, taking up most of the first mobile screen. This is hypothetical, not a measured site result.
The editor selects the few major reader tasks and keeps the finer detail within each section. They assign stable anchors and check the destination labels. The developer discovers that the mobile header covers headings after a jump and evaluates a scoped offset adjustment.
The team tests the logged-out page, direct section links and keyboard activation. The completion note records working navigation rather than claiming a ranking gain or an invented reduction in bounce rate.
The useful improvement is a shorter decision map with verifiable destinations. It helps a reader reach a task without requiring the editor to pad the article or repeat keywords in the navigation.
Maintain anchors when content changes
When revising a heading, distinguish its visible wording from the identifier used by links. If the section's purpose remains the same, preserving the stable identifier can avoid unnecessary link breakage. If its meaning changes substantially, review incoming links and update the navigation deliberately.
Record anchors referenced in newsletters, support messages or other articles where practical. A section can be an important shared destination even if the page URL itself has not changed.
After merging or deleting a section, check the table and any known links. Do not leave a plausible-looking entry pointing to a destination that no longer exists.
Troubleshooting and common mistakes
The link does nothing
Check the exact fragment and identifier, including capitalization and accidental spaces. Then verify the intended heading actually receives that identifier in the delivered page.
The link reaches the wrong heading
Look for duplicate identifiers and competing automatic anchor generation. Establish one clear source rather than repeatedly changing the visible label.
The table appears twice
Inspect the template and content component. Remove or disable only the redundant instance through the supported implementation, preserving the intended navigation.
The page jumps before images finish loading
Ask the developer to investigate layout behavior and the final destination after loading. Test the actual page rather than assuming a smooth-looking preview represents every device.
Someone calls section links an SEO ranking shortcut
Evaluate them as useful navigation. Do not guarantee search-result enhancements or ranking changes from adding a table.
Frequently asked questions
Does every article need a table of contents?
No. Add one when the page contains useful independent destinations and the map reduces effort.
Is a plugin required?
No. The documented anchor-link mechanism provides a manual baseline. Existing components may be appropriate when their maintenance and behavior suit the site.
Should I include all H2s and H3s?
Choose the depth that helps readers. A complete heading inventory and a usable navigation map are not always the same thing.
Can I link directly to a section from another article?
Yes, using the page URL and its fragment. Verify that both the destination page and section remain available when publishing or updating that link.
Conclusion
Choose meaningful destinations, keep anchors stable and test the real page with its actual header. A useful table of contents is a maintained navigation feature, not a decorative heading dump. Its success is that readers can reach the correct visible section reliably.
Need help applying this?
Get a practical review focused on the issue, evidence and next actions.
Contact Shahzaib