Table of Contents: Format and Rules

In the element library , a quick overview and table of contents tell readers what a page covers, what it will help them decide, and how to jump to the section they need.

Quick overview. Use this paired opening element on long or structurally complex pages. Write a 40–90 word overview that sets scope and expected outcome, then provide a contents list made from stable H2 headings and only useful H3 headings. On this site, the live contents control below stays hidden until the reader has scrolled more than 300 pixels; it then appears as a fixed desktop dropdown beneath the site header.

Why this element matters

Readers do not begin every long page at the same point. One person needs a definition, another wants implementation steps, and a third is checking a single constraint before approving work. A short overview answers “Am I in the right place?” before the reader invests attention. The contents list answers “Where is the part I need?” without forcing a linear read.

The two parts are specified together because they solve adjacent but different orientation problems. The overview explains the page’s promise, boundaries, and useful outcome in sentences. The contents list exposes the route through that promise as destinations. A contents list without an overview can show that a page has sections called “Configuration” and “Accessibility” but cannot explain whether the page is a conceptual introduction or a production specification. An overview without navigation can establish scope but still make a reader hunt through 3,000 words.

This element also improves machine extractability, meaning the ability of software to isolate a passage and retain its purpose outside the full page. The overview is a second concise, self-contained summary after the title and description. Hugo’s source table of contents is a linked, machine-readable outline of the page’s coverage and hierarchy; the current sticky renderer converts those links into options that retain their URL fragment values, the #section part of a URL. Search systems, retrieval tools, browser extensions, and AI agents can use the document outline to identify likely answer regions before processing every paragraph. This does not guarantee a search feature or AI citation; it reduces ambiguity about where subjects begin and how they relate.

The pairing must not create repetition. An overview states scope and outcome. A direct answer block answers the primary question. The key takeaways state conclusions worth remembering. When all three say the same thing in different boxes, the opening becomes an obstacle rather than an aid.

When to use it

The contents list earns its place when jumping is a likely reader behavior. Word count is a useful proxy, but structure is the deciding factor.

Use the overview alone when the title could be interpreted broadly, when the page deliberately excludes adjacent subjects, or when the reader needs to know the expected outcome before proceeding. A 900-word policy page may need a two-sentence overview even though it does not need navigation.

Use the contents list alone only when the title and opening already make scope unmistakable. This near-miss is common on reference pages: the opening may contain a direct definition that performs the orientation job, while a long set of independent fields still needs navigation.

Do not use either part as decoration. A six-item TOC on a 700-word article adds an extra decision before the answer. An overview that says “This guide explores everything you need to know” does not define scope, outcome, or exclusions. Do not use the pair to conceal a weak heading structure: if headings overlap, use inconsistent grammar, or divide one idea into many tiny sections, fix the document before exposing its outline.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Position is part of the element’s meaning. The overview must appear after the hero or opening direct answer and before the first H2. It may be a short paragraph or a compact list, but it must be encountered before the reader commits to the body. The TOC invocation belongs immediately after the overview so the authored source keeps orientation and navigation together, even though this site’s sticky control becomes visible only after scrolling 300 pixels.

The pair may not interrupt a definition, separate a claim from its evidence, or appear for the first time midway through the document. Do not place it between a heading and that heading’s opening paragraph: the relationship between heading and explanation should remain direct. Do not place another overview-style component immediately beside it. When a direct answer or key-takeaways block is required, assign distinct jobs and use this order: direct answer, short scope overview, TOC invocation, first body section. Omit one of the summaries if the wording still overlaps.

Use the shortcode once per page. Its rendered IDs (tocDropdown, tocSelect, selectTrigger, and related controls) are fixed, so a second instance creates duplicate document IDs and unpredictable scripts.

Anatomy

The element has six meaningful regions. The first five are content or behavior; the progress indicator is status. The legend is kept in the page so it remains readable when the screenshot is resized or replaced.

1. Overview body: 40–90 words stating scope, intended outcome, and any important boundary.
2. Sticky wrapper title: the page title by default, or the authored title attribute when a shorter label is clearer.
3. Current-section label: starts as “Select section…” and changes as the browser’s IntersectionObserver, an API that detects elements entering a defined viewport region, marks sections active.
4. Dropdown trigger: opens the generated list of section destinations on click in the current implementation.
5. Heading options: links derived from Hugo’s page table of contents, currently H2 and H3 because of markup.toml.
6. Progress bar: shows the proportion of the total scrollable document traversed; it does not identify section completion.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

The gallery covers behavior states rather than decorative themes. The underlying content remains the same so reviewers can compare timing, hierarchy, clipping, and interaction.

No alternate visual variants are authored through Markdown. title changes the label and class adds wrapper classes, but neither creates a semantically different element. New color, card, sidebar, or inline-list treatments require a component decision rather than an arbitrary class added in content.

Parameters

The overview and TOC share one editorial contract, but only the sticky TOC is rendered by the current shortcode. Configuration values are included because they change output even though authors cannot set them per invocation.

The dependency is easy to miss: a page with no H2 headings silently renders no sticky TOC because Hugo produces no usable outline and the partial emits markup only when it has headers. With the current configuration, H2 and their H3 descendants are eligible; H4 and deeper headings are excluded. The partial normally parses Hugo’s .TableOfContents. Its HTML fallback scans rendered H2 elements only, so authors must not rely on fallback behavior to preserve H3 navigation.

Syntax and code examples

The portable notation keeps the overview as the element body and the navigation settings as attributes. Heading links remain generated from the surrounding document rather than duplicated by the author.

:::quick-overview-and-toc{title="On this page" class=""}
This guide explains when to use the element, how the sticky Hugo control behaves,
and how to preserve accessible, stable section destinations after publication.
:::

The current Hugo mapping writes the overview as normal Markdown and invokes the shipped shortcode once. There is no JSON body.

This guide explains when to use the element, how the sticky Hugo control behaves,
and how to preserve accessible, stable section destinations after publication.

{{< table-of-contents title="On this page" class="" >}}

The WordPress block mapping stores the same body and attributes. A site that has not registered the block may use the equivalent shortcode form; it must not hand-author the heading links.

<!-- wp:amicited/quick-overview-and-toc {"title":"On this page","className":""} -->
<p>This guide explains when to use the element, how the sticky control behaves,
and how to preserve accessible, stable section destinations after publication.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="On this page" class=""]
This guide explains the element's scope, behavior, and anchor policy.
[/amicited_quick_overview_toc]

Across all three systems, the source of truth is the document’s real heading hierarchy. A manually maintained list will drift as headings change and can point to IDs that are no longer present.

Examples

Good example

Quick overview. This guide shows content teams how to plan, write, review, and maintain a comparison page. It covers evidence standards, comparison criteria, product claims, accessible tables, and post-publication checks. It does not cover paid placement or affiliate commission terms.

On this page: Define the decision · Select comparison criteria · Gather evidence · Draft the page · Review claims · Measure and maintain

This works because the overview names the audience, outcome, coverage, and boundary in 48 words. The six destinations are distinct tasks a reader might revisit independently. Their labels use parallel verb phrases, so both people and machines can infer a process. None of the entries repeats the page title or exposes a trivial subsection.

Bad example

Overview: Welcome to our complete guide. In today’s changing world, there is a lot to know, so read on to learn everything.

Contents: Introduction · More information · Important things · Other things · Conclusion

This fails for two reasons. The overview spends 22 words without defining scope, reader, outcome, or exclusion. The entries label rhetorical containers rather than subjects, so they do not help a reader predict where an answer lives. Adding more headings would not fix it; the document needs meaningful section boundaries first.

A second near-miss is a 600-word answer with “Overview,” “Background,” “Details,” “Tips,” and “Conclusion” in its TOC. Even if every anchor works, the list adds more interface than navigation value. Keep the direct opening and remove the TOC.

Schema markup and accessibility

Here, schema markup means standardized machine-readable code that identifies entities and properties. This element has no dedicated type or property in the Schema.org vocabulary, and the Hugo shortcode emits no JSON-LD, the script-based notation commonly used to publish that vocabulary. Do not mark the TOC as ItemList merely because it is a list; that would suggest a list of subject items rather than navigation. The overview may inform a page’s description only when the wording is independently suitable, but it is not copied into structured data automatically.

HTML and ARIA behavior matter more here. ARIA, the Accessible Rich Internet Applications standard, supplies roles, names, and states when native HTML does not. A landmark is a named page region that assistive-technology users can jump to. Focus is the current keyboard interaction target.

These are implementation facts, not permission to ignore accessibility. Content reviewers can verify heading clarity, unique IDs, and logical order today. Component owners must resolve trigger, landmark, focus, URL, and reduced-motion behavior before describing the sticky variant as keyboard accessible.

Writing rules

Write the overview after the page structure is stable. This prevents an early promise from drifting away from the finished coverage. Keep it between 40 and 90 words. Prefer two or three sentences; use three to five bullets only when the page contains several genuinely parallel outcomes. State what the page helps the reader understand, decide, or do. Name an exclusion when the title could reasonably promise more than the page delivers.

Use H2 for the page’s major questions, stages, or decision areas. Include H3 in navigation only when it is a useful independent destination under a substantial H2. On this site, configuration includes every H2 and H3 automatically, so the practical policy is stricter: do not create a heading unless it deserves to appear in navigation. Aim for 5–18 total entries. If the generated list exceeds 18, combine overlapping sections, remove unnecessary H3 headings, or split the page. Never skip directly from H2 to H4 to hide a heading from the TOC; heading levels express hierarchy, not styling or navigation preference.

Use concise, descriptive heading text. A reader should understand each destination without reading its parent paragraph. Prefer parallel forms within a sequence: “Choose criteria,” “Gather evidence,” and “Review claims” are easier to scan than a mixture of nouns, questions, and vague labels. Do not put citations, promotional claims, emoji, status badges, or full sentences in a heading solely to influence the TOC.

The overview must never contain a second miniature contents list, unsupported performance claims, or instructions that appear nowhere in the body. The TOC must never contain manually typed anchors, destinations outside the current page, or links to empty sections.

Anchor stability policy

A heading ID is the fragment portion of a URL, such as #anchor-stability-policy. Published fragment URLs are public interfaces. Bookmarks, campaign links, support documentation, search results, and AI-generated answers may point directly to them. Changing the heading text can change Hugo’s generated ID and break every inbound anchor even when the page URL stays the same.

After publication, freeze the IDs of all H2 and H3 headings. Prefer editing the paragraph beneath a heading over renaming the heading. When a rename is necessary, preserve the old ID using an explicit-anchor mechanism supported by the publishing system, then verify both the old inbound fragment and the new TOC selection. Never reuse an old ID for a different subject, never duplicate an ID on the page, and never translate an ID on an existing localized URL without a migration plan. Record intentional anchor changes in the release note or content change log so owners of known inbound links can update them.

Post types that use it

The postTypes frontmatter lists the formats for which this element is part of the production pattern. It is still conditional: a short instance of a normally long format may fall below the TOC threshold.

Product, category, and use-case pages are not included by default because their primary journeys are often handled by page-level navigation and calls to action. Add this element only through a documented template decision, not because the page happens to be long.

QA checklist

• Confirm the page meets the threshold: at least 1,800 words, seven H2 sections, or a documented non-linear navigation need.
• Confirm the overview is 40–90 words and states scope, intended outcome, and any necessary exclusion.
• Confirm the overview does not repeat the direct answer or key takeaways.
• Confirm the shortcode appears once, immediately after the overview and before the first H2.
• Confirm every H2 is a meaningful major destination and every H3 is useful enough to appear in navigation.
• Confirm the generated list contains 5–18 entries, uses a logical order, and contains no H4 items under the current configuration.
• Confirm config/_default/markup.toml still uses startLevel = 2, endLevel = 3, and ordered = false, or update this specification with the component change.
• Confirm a page with no eligible H2 does not claim to contain a TOC; the shortcode will silently render nothing.
• Confirm every generated fragment is unique and reaches the intended heading.
• Test published inbound anchor URLs before changing any H2 or H3 wording; preserve old IDs when headings must change.
• On desktop, verify the sticky wrapper is hidden at 300 pixels or less and appears after the scroll position exceeds 300 pixels.
• Verify the fixed wrapper sits beneath the actual header, the progress bar advances, and the active label follows section changes.
• Verify narrow viewports do not show the current control, and record this as expected current behavior rather than a broken screenshot.
• Record the current accessibility limitations: no navigation landmark, no keyboard-focusable visible trigger, no focus transfer, no fragment update, and no reduced-motion branch.
• Confirm no screenshot path is rendered until the corresponding asset exists on disk.

FAQ

The questions below cover the editorial decisions that most often cause this element to be added too early, made too deep, or broken after publication.