Table of Contents

Use the af-toc pattern to style in-page navigation (e.g. “On this page” lists, long-form docs, multi-section pages).

Markup (recommended)

Use semantic HTML:

• nav with aria-label
• an optional heading (h2/h3) for the TOC title
• ol/ul for the list

Contents

1. Introduction
2. Getting started
3. Components
   1. Buttons
   2. Forms
4. Conclusion

<nav class="af-toc" aria-label="Table of Contents">
  <h2 class="af-toc-title">Contents</h2>
  <ol>
    <li>
      <a href="#introduction">Introduction</a>
    </li>
    <li>
      <a href="#getting-started">Getting started</a>
    </li>
    <li>
      <a href="#components">Components</a>
      <ol>
        <li>
          <a href="#buttons">Buttons</a>
        </li>
        <li>
          <a href="#forms">Forms</a>
        </li>
      </ol>
    </li>
    <li>
      <a href="#conclusion">Conclusion</a>
    </li>
  </ol>
</nav>

Active link state

If you can set aria-current="page" on the active anchor, the TOC will highlight it.

Contents

1. Introduction
2. Usage

<nav class="af-toc" aria-label="Table of Contents">
  <h2 class="af-toc-title">Contents</h2>
  <ol>
    <li>
      <a href="#intro" aria-current="page">Introduction</a>
    </li>
    <li>
      <a href="#usage">Usage</a>
    </li>
  </ol>
</nav>

Automatic styling (no class)

The pattern also styles semantic TOCs without the class when the nav’s label suggests “contents”:

Contents

1. Section A
2. Section B

<nav aria-label="Table of contents">
  <h2>Contents</h2>
  <ol>
    <li>
      <a href="#a">Section A</a>
    </li>
    <li>
      <a href="#b">Section B</a>
    </li>
  </ol>
</nav>

Notes

• If you’re using the docs site, Starlight’s built-in TOC uses nav[aria-label="Table of contents"], which this pattern can style without extra markup changes.
• You can nest lists (ol > li > ol) for hierarchical pages. Nested items are numbered with the parent prefix (3.1, 3.2).