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

Code Live

<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>

Contents

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

Active link state

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

Code Live

<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>

Contents

1. Introduction
2. Usage

Automatic styling (no class)

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

Code Live

<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>

Contents

1. Section A
2. Section B

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.