@domternal/extension-toc

Notion-style Table of Contents for the Domternal editor.

A shared heading-discovery data layer feeds three pieces that work together:

• TableOfContents - the headless heading observer that maintains a reactive heading list in editor.storage.toc and exposes the scrollToHeading command.
• FloatingTocOutline - a sticky right-rail outline with a hover-expanded card, anchored to the editor or the viewport.
• TableOfContentsBlock - a block-level atom node, inserted from the slash menu by typing /toc.

Active-heading tracking, smooth click-to-jump scrolling, and initial-load #hash navigation are built in.

Links

Website    •    Documentation    •    Live examples

Install

pnpm add @domternal/extension-toc

@domternal/core and @domternal/pm are peer dependencies. TableOfContents also requires the UniqueID extension (from @domternal/core) to be loaded: it reads UniqueID's id attribute on headings as the navigation anchor and stays inert without it.

Version 1.2.0 requires both @domternal/core and @domternal/pm in the range >=1.2.0 <2.0.0. Upgrade these packages together with this extension.

Usage

import { Editor, StarterKit, UniqueID } from '@domternal/core';
import {
  TableOfContents,
  FloatingTocOutline,
  TableOfContentsBlock,
} from '@domternal/extension-toc';
import '@domternal/theme';

const editor = new Editor({
  element: document.getElementById('editor')!,
  extensions: [
    StarterKit,
    // UniqueID's default `types` already stamps headings; pass `types` only
    // when TableOfContents' `anchorTypes` point at custom node types.
    UniqueID,
    TableOfContents.configure({ levels: [1, 2, 3] }),
    FloatingTocOutline.configure({ anchor: 'editor' }),
    TableOfContentsBlock,
  ],
});

// Jump to a heading by its UniqueID-assigned id (updates the URL hash).
editor.commands.scrollToHeading('introduction');

// Read the live heading list, or subscribe via the onUpdate option.
console.log(editor.storage.toc.content); // HeadingEntry[]

UniqueID stamps ids on headings; TableOfContents watches the document and keeps editor.storage.toc in sync; FloatingTocOutline renders the sticky outline; TableOfContentsBlock adds the /toc atom so users can drop a contents list into the document.

Options

TableOfContents.configure({ ... }):

• levels (default [1, 2, 3]) - heading levels to track
• anchorTypes (default ['heading']) - node names treated as anchors. Every type listed here must also be in UniqueID.options.types
• onUpdate - called with the storage object whenever the heading list or the active heading changes

Activity tracking belongs to TableOfContents, so HeadingEntry.domNode, isActive, and isScrolledOver stay current even without FloatingTocOutline. The inline block, floating outline, and scrollToHeading command share its navigation state. These observer options are also accepted:

• activeScrollParent (default null, meaning the window): the scroll container
• activeRootMargin (default '0px 0px -85% 0px'): the observer margin that schedules measurements
• activeOffset (default 0): the activation line in pixels below the scroll root's inner top
• clickOverrideMs (default 500): how long a navigation target stays active while scrolling catches up

Explicit TableOfContents options take precedence. Omitted scroll-parent, root-margin, and click-override options inherit the corresponding legacy FloatingTocOutline options, preserving existing configurations. Use activeOffset to move the activation line; root margin controls observation.

FloatingTocOutline.configure({ ... }):

• anchor (default 'editor') - 'editor' pins the outline to the editor container's right gutter, 'viewport' fixes it to the right edge of the viewport
• minHeadings (default 1) - hide the outline while the document has fewer headings than this
• mobileBreakpoint (default 1024) - viewport width in px at or below which the outline is hidden; 0 never hides it
• activeScrollParent (default null, meaning the window) - scroll container for the active-heading tracker. Set it when the editor lives in its own scrolling region
• activeRootMargin (default '0px 0px -85% 0px') - IntersectionObserver rootMargin used to schedule active-heading measurements
• clickOverrideMs (default 500) - how long scroll-derived updates are ignored after a tick is clicked, so the click target stays active until the scroll lands
• hoverInDelay / hoverOutDelay (defaults 120 / 350) - ms before the expanded card appears and before it collapses back to ticks
• outlineHost - (view: EditorView) => HTMLElement overriding where the outline DOM mounts. The default walks up from the editor's DOM to the first ancestor whose computed overflow is not hidden

TableOfContentsBlock.configure({ ... }):

• emptyStateText (default 'Add headings to create a table of contents.') - placeholder shown while the document has no headings
• HTMLAttributes - extra attributes for the block wrapper

Exports

import {
  TableOfContents,
  tocPluginKey,
  FloatingTocOutline,
  floatingTocOutlinePluginKey,
  TableOfContentsBlock,
  walkHeadings,
  scrollToHeading,
  createActiveStateTracker,
} from '@domternal/extension-toc';

walkHeadings, scrollToHeading, and createActiveStateTracker are exposed as standalone helpers so you can build a custom outline UI on top of the same data layer and active-tracking rule.

The tracker snapshot type is exported as ActiveStateSnapshot, with activeId and scrolledOverIds. The saved inline node remains tableOfContents; no document migration or change to UniqueID defaults is required.

Localization

This package exports tocMessages for typed custom catalogs. Optional German UI messages and search aliases are available from @domternal/extension-toc/locales/de as deMessages and deSearchAliases. Merge them with the core and other enabled feature catalogs. Missing entries fall back to English. Authored heading text remains unchanged.