Tiptap table of contents: build a heading sidebar from live anchor data

A workshop handbook might contain two sections named “Before starting,” one for the camera station and one for the audio station. A sidebar built only from heading text can confuse those destinations. Use each anchor's generated identity for navigation and its text for the visible label.

Render labels as text and keep their anchor identities

For an existing, compatible Tiptap editor setup, add the extension once. This fragment assumes the host page already contains an ordered list named handbook-contents:

import { TableOfContents } from
  '@tiptap/extension-table-of-contents';

const list = document.getElementById('handbook-contents');

const handbookContents = TableOfContents.configure({
  onUpdate(anchors) {
    list.replaceChildren();

    for (const anchor of anchors) {
      const item = document.createElement('li');
      const link = document.createElement('a');
      link.textContent = anchor.textContent;
      link.href = '#' + encodeURIComponent(anchor.id);
      item.dataset.level = String(anchor.level);
      item.append(link);
      list.append(item);
    }
  }
});

Include handbookContents in the editor's existing extensions, together with its heading support. Wrap the list in a navigation element with an appropriate label, such as “Handbook sections.” This small renderer creates a flat list and exposes each entry's level for styling. It does not claim to build a nested list hierarchy automatically.

The current anchor object documents textContent, id, level, originalLevel, isActive, and isScrolledOver, among other fields. Use those documented field names for your installed version. Building the label with textContent keeps heading text from being interpreted as sidebar HTML.

Distinguish a heading's name from its destination

The extension can generate unique IDs; a custom getId function must retain uniqueness even when headings repeat. Using the heading wording alone as a slug is insufficient for the two “Before starting” sections. An ID also needs to survive the application's save and render path if existing reader links should remain useful after a wording edit.

Rename the camera heading to “Camera setup” and inspect both the sidebar label and its destination. Then move that section and remove the audio section. Each surviving list entry should refer to a surviving heading, and removed sections should leave no stale entry. The UniqueID guide explains a related block-identity feature; its custom data-uid attribute is not interchangeable with this extension's navigation attributes.

Check the reader output separately from the editor

An authoring sidebar lives outside the editor document. Saving the editor's JSON or HTML does not automatically save that surrounding sidebar markup. Decide whether the delivered reader needs its own generated contents list and preserve the heading attributes required by that reader. Tiptap's persistence documentation describes the separate JSON and HTML storage choices.

For server rendering, the current extension also documents generateTocIds to assign missing or duplicate anchor IDs in a Tiptap JSON document. Use the same relevant extension configuration on that path. Check the actual rendered headings and links after sanitization rather than assuming the authoring DOM is the delivered page.

Finally, click both repeated-label entries before renaming, then click the surviving renamed entry after a save and reload. Confirm the target in the intended scroll container. The HTML contents guide covers fixed-header offsets on the reading page. Finish with a handbook whose sidebar names and actual section destinations agree in the copy the workshop staff will open.