TOCflow

A server-rendered Table of Contents block for WordPress.
Add one block. Get an accessible, SEO-friendly outline from your headings.

Docs · Download · Issues · GPLv2 or later

What's new — v1.3.3 (Sep 2026)

For WordPress.org reviewers: the sections below describe every change since v1.0.2.

v1.3.3 — Custom colour & font display fix

v1.3.1 — Security & code-quality fix

v1.3.0 — Global design & accessibility settings

All global defaults apply to auto-inserted blocks and shortcodes. Per-block editor settings always override them.

v1.2.2 — WordPress.org compliance fixes

v1.2.1 — Performance patch

v1.2.0 — Study assistant & writer tools

All three reader tools are off by default. They only activate when the author explicitly enables them. No feature writes to the database; no feature makes a network call.

v1.1.0 — Reading Guide, hover previews, citations, page-builder compatibility

Full entry-by-entry detail in CHANGELOG.md.

Performance

TOCflow is built to add zero measurable overhead on pages that don't use it, and minimal overhead on pages that do.

Why TOCflow

• Zero config — insert the block; the outline builds itself.
• Server-rendered — the list is in the first HTML response (SEO + screen readers).
• Accurate anchors — matching ids are injected into headings; custom HTML anchors win.
• Accessible — a <nav> landmark, keyboard-friendly collapse, aria-current while you read.
• Study-ready — reading progress, personal notes, bookmarks, citations, and export — all without any account or server dependency.
• Compatible — Gutenberg, Elementor, Divi, Bricks, Beaver Builder, WPBakery, Oxygen, Breakdance, and every major theme.

Features

• Live preview in the editor as you add or edit headings
• H1–H6 (H1 off by default), numbered or bulleted, five style presets
• Smooth scroll + offset for sticky headers (prefers-reduced-motion respected)
• Collapse/expand, sticky outline, scroll-spy highlight
• Auto-insert (top of content or after the first heading)
• [tocflow] shortcode for classic content and page builders
• Skip a heading with the class no-toc
• Optional ItemList JSON-LD schema
• Settings + Docs & Support screens in wp-admin

The plugin slug, folder, and text domain are tocflow. Display name: TOCflow. See docs/NAMING.md.

Install

Current version: 1.3.1.

1. Download tocflow.zip from Releases.
2. In WordPress: Plugins → Add New → Upload Plugin.
3. Activate. Optional: Settings → TOCflow.

Or clone this repo into wp-content/plugins/tocflow, run npm install && npm run build, and activate.

Use the block

1. Edit a post that has Heading blocks.
2. Insert Table of Contents (usually right after the intro).
3. In the sidebar: title, heading levels, list style, preset, collapse, sticky.

Shortcode

[tocflow]
[tocflow title="On this page" ordered="1" style="boxed"]

Documentation

Develop

Requires Node.js 20+ (see .nvmrc).

git clone https://github.com/matthummel-pa/tocflow.git
cd tocflow
npm install
npm run start          # watch
# npm run build        # production
npm run lint:js
npm run lint:css
npx --package=@wordpress/env wp-env start   # optional local WordPress

The compiled build/ directory is gitignored — build at least once before activating the plugin.

PHP: composer install then composer phpcs. See docs/DEVELOPER_SOP.md and CONTRIBUTING.md.

License

GPLv2 or later — the whole plugin (PHP, JavaScript, CSS, and images), same family as WordPress.

Copyright © 2026 Matt Hummel.