Table of contents
A table of contents lists the sections of a page and links to each one. It is a
nav that opens with a heading, followed by an ordered list of links to the
sections' ids. No class is needed: a nav that starts with a heading is laid out as a list
down the page rather than a bar.
A contents list
This is the contents of this page, and the links work. Each one points at a section's
id, and the page scrolls so the section lands just below the sticky
header.
<nav class="card" aria-label="Contents">
<h3>Contents</h3>
<ol>
<li><a href="#contents">A contents list</a></li>
<li><a href="#nested">Nested sections</a>
<ol>
<li><a href="#nested-lists">Lists inside lists</a></li>
<li><a href="#numbering">Numbering</a></li>
</ol>
</li>
<li><a href="#beside">Beside the content</a></li>
<li><a href="#accessibility">Accessibility</a></li>
</ol>
</nav>
Nested sections
The list follows the page's outline. A section inside a section gets a list inside the list item of its parent.
Lists inside lists
Put the inner ol inside the parent's li, after its link, as
in the contents above. Nesting more than two levels deep is rarely worth it: the list
gets long and the top-level sections become hard to pick out.
Numbering
An ol numbers its items, and each nested list counts from one again. The
numbers are the browser's own list markers, so they are read out with the list, and
they take the accent colour like every other list marker.
Beside the content
On a long page, put the contents in the aside of a sidebar layout and make it sticky, so it stays in view as the reader moves through the page. On a narrow screen the aside drops above or below the content.
Here the article scrolls inside a box, so the aside sticks to the top of the box at
top: 0, and its links jump to the parts of that article: scroll it or click
a link to see. On a page, use top: calc(var(--pinned) + 16px) instead, so
the contents comes to rest just below the site header.
<div role="region" aria-label="Long article" tabindex="0" style="max-height: 220px">
<div class="sidebar">
<div class="column">
<section id="part-one">
<h3>Part one</h3>
<p>The first part of a long article, which sets out what it will cover.</p>
</section>
…
</div>
<aside style="position: sticky; top: 0">
<nav aria-label="Article contents">
<h3>Contents</h3>
<ol>
<li><a href="#part-one">Part one</a></li>
<li><a href="#part-two">Part two</a></li>
…
</ol>
</nav>
</aside>
</div>
</div>
Lighting up the section the reader is currently in, as they scroll, needs a script. That is the scrollspy.
Accessibility
nav- A navigation landmark, named Contents so it is not confused with the site menu.
- The heading
- A real heading, so the contents also shows up when a screen reader lists the page's headings. Pick its level to fit where it sits in the outline.
- Link text
- Each link reads the same as the heading it points to, so the reader knows where it goes.