Tocnest Table of Contents

Tocnest helps readers find their way through long articles. Add the Tocnest block in the editor, or let automatic insertion handle your posts. All features are included, without accounts, license keys or upgrade notices.

What makes Tocnest distinct

• One-click migration and batch post conversion: Built-in importer for LuckyWP Table of Contents global settings, lazy runtime compatibility for existing [lwptoc] shortcodes and saved blocks, undo snapshot protection, and a batched AJAX converter (200 posts per request) for per-post metadata overrides without modifying post content in the database.
• Native Gutenberg block with live ServerSideRender preview: Purpose-built block (apiVersion: 3) with Inspector controls and live server-rendered preview, plus automatic duplicate suppression when a manual block or shortcode is present.
• Zero-jQuery, WCAG-accessible semantic <nav> markup: Uses semantic <nav> and nested <ol>/<ul> lists, aria-expanded and aria-controls toggle state, aria-current="location" active section tracking via IntersectionObserver, keyboard focus management, and prefers-reduced-motion support. If JavaScript is disabled, the table of contents stays open and every link works.
• Deterministic heading ID collision handling: Preserves existing author heading IDs across the entire document, reserves IDs across multiple posts rendered in the same request, supports transliterated or Unicode slugs, and appends deterministic -2, -3 suffixes on collision.

Key features

• Works immediately on posts with at least three h2-h4 headings.
• Automatic placement, a [tocnest] shortcode and a classic widget.
• Decimal, nested decimal, Roman and nested Roman numbering.
• Heading filters by level, text, wildcard and CSS class. The tocnest-skip class always excludes a heading.
• Five color schemes, six color overrides, font controls and responsive sizing.
• Smooth scrolling with a sticky-header offset, reduced-motion support and optional section highlighting.
• Per-post controls in both editors and optional anchors without a visible TOC.

Tocnest only loads its small CSS and vanilla JavaScript when a TOC renders. Tocnest renders on singular post views. Password-protected posts, excerpts, feeds, public REST/JSON requests and nested content filters never expose a TOC. The authenticated block editor preview is supported.

Privacy

No data is collected or sent anywhere. Tocnest performs no external requests and loads no remote assets. Settings and per-post overrides stay in your own database. Uninstall removes Tocnest settings, import backups and reports, the detection cache and Tocnest per-post overrides from each site. Previous plugin data and post content are preserved.

Migrating from another table of contents plugin

Import settings from the LuckyWP Table of Contents plugin through Settings > Tocnest > Import. Tocnest is independent and is not affiliated with that plugin or its authors.

1. Make a site backup and open the Import tab. Review detected option groups and post counts. Counts are capped at 10,001 and cached for five minutes.
2. Click Import settings. General, appearance, automatic insertion, anchor-only post types and miscellaneous options are mapped. A report identifies unsupported or unknown values. Compatibility is enabled automatically.
3. Deactivate the previous plugin. Old [lwptoc] shortcodes and saved contents blocks now render through Tocnest. They are registered only when the previous plugin is inactive and compatibility is enabled.
4. Per-post settings work lazily without database writes. Optionally choose Convert per-post settings now to process 200 posts per request with progress. Existing Tocnest overrides are preserved.
5. Undo import restores the global Tocnest settings from before the first import. It does not remove converted per-post settings. Repeated imports keep that original snapshot until you undo.

The old contents block remains editable as a compatibility block. To use the new Inspector, replace it with a Tocnest block; no editor conversion step is required for existing content to render. Existing legacy widget instances (id lpwtoc_widget) are not changed automatically; replace those widgets with the Tocnest block or classic widget.

While both plugins are active, a notice appears only on this settings page and Tocnest pauses automatic insertion when the previous auto insertion is enabled. Advanced settings offers an explicit override.

Mapping details: excluded h1-h6 levels are preserved; depth remains relative nesting depth. All five numbering styles, three suffixes, five positions and five schemes map directly. Font weight names map to CSS 100 through 900. Default font sizes become 1em. The rightwithoutflow float becomes a standard right float and div lists become accessible ul lists. Pipe-separated skip patterns honor escaped pipes and become one pattern per line. The asheadingwotransliterate anchor format preserves original characters. Unknown enums fall back to Tocnest defaults. wrapNoindex is unsupported and reported as skipped. Null or missing per-post values inherit global settings.

Developers

Filters:

• tocnest_settings ($settings): global settings before shared schema validation.
• tocnest_should_render ($allowed, $post): veto rendering.
• tocnest_headings ($headings): heading records before selection and rendering, with id, text, level and class keys.
• tocnest_anchor ($anchor, $text, $heading): customize a generated ID before uniqueness checks.
• tocnest_html ($html): final escaped TOC HTML. Extensions must escape their own additions.
• tocnest_post_types ($types): automatic insertion post types.

Actions: tocnest_before_render ($post, $settings) and tocnest_after_render ($post, $settings) run around successful rendering. Use them for integration side effects; filter tocnest_html to alter output.