Table of contents

The problem it solves

Long documents such as guides, reference pages, policies and reports are rarely read top to bottom. People arrive with a question and look for the section that answers it. Without an overview they scroll and skim, and miss sections below the fold. A table of contents shows the structure of the document at a glance and takes people straight to the section they want.

This library uses one on every document: the "On this page" list beside the text.

When to use it

• The page is long, with several sections people may want separately.
• The sections have clear, descriptive headings.
• People come back to the page to look things up, not to read it again in full.

When not to use it

• Do not add one to a short page with two or three sections. The headings themselves are enough.
• Do not list headings that do not describe their content, such as "Overview" and "More". Fix the headings first.
• Do not use it to replace navigation between pages. It covers one page.

How to build it

Content and order

Build the list from the page's own headings, in the order they appear, so the two never drift apart. Include the second level, and the third only when the page is very long. Generate stable anchor ids from the heading text, so links to a section keep working when other sections change.

Placement

On wide screens, place the list beside the text and keep it visible while the page scrolls, highlighting the section in view. On narrow screens, place it above the content, collapsed or short, so it does not push the first section far down.

Accessibility

• Wrap the list in a nav element with an accessible name such as "On this page".
• Use real links to the section anchors, so the target moves focus and works with the back button.
• Make sure each target heading is a real heading element, so screen reader users can also navigate by headings.