CKEditor table of contents: insert a heading list that updates as authors edit

Consider a maintenance handbook whose “Weekly checks” section becomes “Before each shift.” A manually typed contents list can keep the old wording for weeks. An editor-generated list should follow the heading change while the author is still working on the handbook.

Use heading structure before inserting the list

Create actual headings with the editor's heading control. Making a paragraph large and bold does not give it the same document role.

For a small original handbook fixture, use these headings:

Heading 1: Pump maintenance
Heading 2: Before each shift
Heading 3: Check the inlet screen
Heading 2: Monthly inspection

Place the caret where the reader should find the contents list and choose the table-of-contents toolbar button. A heading-level change should alter the list's hierarchy, and a wording change should alter its text. The official demo specifically recommends changing headings to observe the live update.

Add the plugin and toolbar entry together

The current feature documentation imports TableOfContents from ckeditor5-premium-features. Add it to the existing editor's plugins and add tableOfContents to its toolbar:

import { TableOfContents } from 'ckeditor5-premium-features';

// Merge these additions into your existing, licensed editor config:
const contentsAdditions = {
  plugins: [TableOfContents],
  toolbar: ['tableOfContents']
};

Keep the rest of your document configuration, including the heading features, required base plugins, styles, and valid license setup. The fragment above does not initialize a complete editor or supply premium credentials. Consult the current official installation section for the package or CDN route your project uses.

The plugin registers insertTableOfContents, which can be invoked through the editor command interface:

// editor is your already initialized CKEditor instance.
editor.execute('insertTableOfContents');

A toolbar item absent from a build, a feature unavailable under the configured credentials, and a document with no useful headings are different problems. Check which condition applies before trying to rewrite the generated list as ordinary paragraphs.

Separate inserted navigation from an outline beside the editor

The Table of Contents widget is inserted into document content. CKEditor's Document Outline displays a list beside the editor, and its Content Minimap is another authoring navigation view. A sidebar that helps the author move around is not automatically the contents block a reader receives in exported HTML. The official related-features section distinguishes these options.

For the maintenance handbook, use the inserted contents block if technicians need navigation within the delivered document. Use an outline beside the editor if the author mainly needs to move between sections while writing. The two needs can coexist, but verify the delivered content independently.

Check the saved output outside the authoring surface

The official guide states that the feature manages heading IDs and creates links with href attributes so the output scrolls to the corresponding heading. Preserve those attributes in your storage and rendering pipeline.

Run this focused review with the handbook fixture:

1. Rename “Before each shift” to “At shift handover” and confirm the list text follows.
2. Change “Check the inlet screen” from a third-level to a second-level heading and inspect the hierarchy.
3. Save and reload the document through your actual storage path.
4. Render that saved output in the destination reader and use the inlet-screen entry to reach its heading.

If the jump fails only after publishing, inspect whether the destination renderer stripped an ID or changed an href. If the heading is covered by a sticky bar, adjust the reading page's target spacing; the HTML contents guide covers that layout problem. Neither symptom proves that the editor failed to update its heading list.

Printed page numbers are a separate requirement. A linked heading list does not establish the pagination of a PDF or word-processing export. Confirm any such output in the conversion tool you actually use.

Before sending the handbook for review, ask the maintenance lead to open the delivered copy and reach the inlet-screen check from its contents entry. That verifies the navigation at the point technicians will use it, after the editor and storage pipeline have both done their work.