SlowlyTable of contents
An automatic, accessible list of links built from the page's own headings.
A table of contents block reads the headings already on the page and turns them into a linked list, without anyone typing the list by hand. Add a heading, remove one, reorder a section, and the list follows.
The building happens one of two ways. On a normal post or page, a late content filter scans the rendered HTML for h2 through h6 headings, gives each one a slug id if it doesn't already have one, and fills the block's list — no client script needed for that part. When the block is placed inside a template instead, so the post content never reaches that filter, a small front-end script builds the list itself by scanning a target container, and that script is also where h1 headings, the minimum-headings threshold, and a custom target container take effect. Either way the result is the same shape: a <nav> with a filled list.
Adding one
- Select the section or container to hold it, typically near the top of a long post or page.
- Open the inserter and search "table of contents".
- Pick the block. It fills itself from the page's headings; there's nothing to type.
Settings
In the TOC's own panel. Appearance lives in the shared design panel.
| Setting | What it does | Reach for it when |
|---|---|---|
| Levels | Which heading levels (h1–h6) feed the list | Narrowing to h2/h3 for a clean outline, or widening for a deep reference page |
| Minimum headings | Threshold below which the block hides itself, on the template-built fallback (see above) | Short pages where a two-item TOC isn't worth the space |
| Marker | Numbered, nested numbering (1.1), bullets, or none | Matching the list style to the page's tone |
| List type | Ordered (ol) or unordered (ul) markup | Semantics matter more than the marker choice for some content |
| Show title / Title text / Title tag | The heading above the list, its text, and its HTML tag | Renaming "Table of Contents" or matching heading level to the page outline |
| Collapsible / Open by default | Wraps the list in a native disclosure, and whether it starts open | Long lists on mobile, where a collapsed TOC saves scroll |
| Toggle icon / Icon position | An icon on the disclosure summary, before or after the title | Replacing the default browser triangle |
| Smooth scroll | Animates the jump instead of snapping | Almost always on; disabled automatically for reduced-motion visitors |
| Scroll offset | Pixels held back so a sticky header doesn't cover the target heading | A fixed header sits over the top of the page |
| Active section highlight | Marks the link for whichever heading is currently in view | Long-scroll pages where readers want to track their position |
| Target container | CSS selector the fallback script scans instead of the main content area (see above) | Template-composed pages, or a TOC that should cover only part of the page |
| List class / Item class | Extra classes on the list and each item | Hooking into custom CSS beyond the design panel |
Styling
The shared design panel covers spacing, type, colour, and borders. TOC-specific look, the marker style, the disclosure icon's rotation on open, the active link's added weight, comes from toc.css and can be overridden from custom CSS or the list/item class fields above.
Accessibility
The active-section indicator sets aria-current="location" on the link for whichever heading is currently in view, using an IntersectionObserver. If that script never runs, the TOC is still a fully working list of links, just without the live indicator. Collapsible mode uses a native <details>/<summary> element rather than a custom widget, so keyboard and screen reader support come for free. The list's title becomes the aria-label on the surrounding nav landmark, so a page with more than one navigation region stays distinguishable.