Live editor preview
The outline updates in real time as you add or reorder Heading blocks. No placeholder-only box.
WordPress plugin · slug tocflow · v1.2.0
TOCflow is the first Table of Contents block with a built-in Reading Guide — section previews, read-time estimates, hover tooltips, emoji reactions, and one-click academic citations. Server-rendered. Zero external APIs. Works with every theme and SEO plugin.
What it does
All the things you'd expect from a TOC plugin, built properly on the WordPress block editor with no shortcuts.
The outline updates in real time as you add or reorder Heading blocks. No placeholder-only box.
The <nav> is in the HTML response. Search engines and screen readers see it before any JavaScript runs.
Custom HTML anchors on a heading win. Anchors are injected at render time using the same slug map as the list.
Default, Minimal, Boxed, Underline, Card — all switchable from the Styles panel with a single click.
Keep the TOC in view while scrolling. Let readers collapse it. Highlight the active section as they scroll.
Generate the TOC at the top of content or after the first heading across all posts — no per-post editing needed.
[tocflow] for Classic Editor content, widgets, and theme templates via do_shortcode().
Proper <nav> landmark, ARIA labels, keyboard navigation, and aria-current on the active link.
Optional ItemList schema markup. Opt-in and off by default — safe alongside Yoast, Rank Math, and Schema Pro.
New in v1.2.0 — study assistant
Opt-in tools for long-form reading. State stays in the reader’s browser — no accounts, no server, no tracking.
A 📝 button on each section lets readers jot personal notes. Stored in localStorage only. Enable with rnotes="1" or the block sidebar toggle.
A thin animated bar shows 0–100% of the document read, based on headings scrolled past. Enable with rprogress="1".
TOCflow remembers the last heading the reader reached and offers a ↩ Resume button on the next visit. Enable with bookmark="1".
Writers mark each heading Draft, In progress, or Done in the editor, and can still attach a reader-facing teaser note.
When Reading Guide + read-time are on, the TOC header shows the aggregated read time for the whole post.
From v1.1.0 — what no other TOC plugin does
Enable one toggle in the block sidebar. Every enrichment is extracted from your block content server-side — zero JavaScript fetches, zero external services, zero accounts.
Hovering over any TOC link pops a floating tooltip with the section's opening text. Reader sees the content without scrolling. Works on keyboard focus too. Smart viewport-aware positioning.
The opening ~20 words of each section appear beneath its TOC link, extracted server-side from your block content. No JS fetch. Works with nested blocks (Group, Columns, Cover).
A thin bar under each TOC link shows that section's word count as a proportion of the longest section. Readers see long vs short at a glance without reading a word.
~N min badge alongside each link, computed at PHP render time (word count ÷ 200 wpm). Readers budget their attention before they click.
As a reader scrolls past each heading, its TOC item fades out. The outline becomes a live checklist of what has been read and what remains.
Type a teaser or hook per heading in the block editor's Section Notes panel. Readers reveal it with a tap. Stored in block attributes — no database round-trip, no extra query.
Readers react per section: 💡 Insightful · ⭐ Saved · 🤔 Unclear · ✅ Got it. Stored in localStorage. Zero server calls. Zero accounts. Zero tracking.
One-click copy of a formatted citation (APA, MLA, Chicago, Harvard, or plain link) for any section, including the direct #anchor. Built from WordPress post meta — no external API.
Settings reference
The block sidebar controls individual block instances. Settings → TOCflow in wp-admin sets site-wide defaults.
| Control | What it does |
|---|---|
| Title text, show/hide, HTML tag | Visible label and document outline tag (P, H2–H4) |
| Heading levels H1–H6 | Which heading levels appear in this TOC |
| Numbered list / nested 1.1.1 | Bullets, sequential numbers, or nested counters |
| Style preset | Default · Minimal · Boxed · Underline · Card (Styles panel) |
| Hide markers, two columns, compact, underline | Layout adjustments |
| Max height | Scroll within the TOC when list overflows |
| Sticky | Keeps the TOC fixed as the page scrolls |
| Collapsible / start collapsed | Reader-controlled toggle |
| Highlight active heading | Scroll-spy marks the section currently in view |
| Smooth scroll / offset override | Per-block override of the site-wide setting |
| Minimum headings | Hide this block when the post has fewer headings |
| Hover section preview | Floating tooltip on hover — no full Reading Guide needed |
| Full Reading Guide | Inline previews, density bars, read time, progress, reactions, citations |
| Section Planner | Per-heading writing status plus author teaser, revealed by reader tap |
| Reader note pads | Private per-section notes in localStorage |
| Reading progress bar | 0–100% document progress from headings scrolled past |
| Resume bookmark | Return-visit jump to the last-read heading |
| Citation format | APA · MLA · Chicago · Harvard · Plain link |
| Control | What it does |
|---|---|
| Smooth scroll | Animate jumps to headings sitewide (respects prefers-reduced-motion) |
| Scroll offset (px) | Space to leave under a sticky admin bar or theme header |
| Highlight active heading | Site-wide default for the scroll-spy feature |
| Minimum headings | Hide the TOC when a post has fewer matching headings |
| Auto-generate position | Off · Top of content · After first heading — sitewide |
| Post types | Which post types get the auto-generated TOC |
| Auto TOC: title, style, layout, heading levels | Defaults for the auto-generated block |
| Schema markup (JSON-LD) | ItemList structured data — off by default, safe with Yoast and Rank Math |
| Delete data on uninstall | Opt-in cleanup — deactivating never deletes data |
Works with your stack
TOCflow inherits the active theme's fonts and colors, outputs a standard <nav> landmark, never loads from third-party CDNs, and makes zero remote calls. It co-exists cleanly with every major plugin and theme in the WordPress ecosystem.
[tocflow] shortcodeUse [tocflow] in any Shortcode, HTML, or Code element. TOCflow automatically reads headings from each builder's stored data and injects matching anchor IDs into the rendered page — no manual slug mapping needed.
[tocflow] in Code module[tocflow][tocflow] works everywheretocflowFound a conflict? Open a GitHub issue — confirmed compatibility is added to this page.
Get going in 3 steps
Skip a heading: Add CSS class no-toc or tocflow-skip to any Heading block (Advanced → Additional CSS class(es)).
Enable Reading Guide: Open the block sidebar → Reading Guide panel → toggle Hover section preview or Full Reading Guide.
Developers: git clone into wp-content/plugins/tocflow, then npm install && npm run build. Source in src/, output in build/.
Frequently asked
Yes — use the [tocflow] shortcode in classic post content, text widgets, or theme templates via do_shortcode('[tocflow]').
No. The JSON-LD ItemList markup is off by default. If you enable it, leave your SEO plugin's TOC schema off, or vice versa. Both cannot be on simultaneously without creating duplicate structured data.
Never. Zero external API calls in any mode. Reading Guide section data is extracted server-side from your block content. Emoji reactions are stored in the reader's browser localStorage. Citations are built from WordPress post meta. No data leaves your server or the reader's device.
Yes. TOCflow is fully translation-ready with a standard tocflow text domain. All user-facing strings are translatable. There are no locale-specific slug issues.
PHP extracts the opening ~20 words of each section from your parsed block content at render time. The text is embedded in the HTML. JavaScript positions a floating tooltip next to the hovered link — no network request.
The § citation button uses only data WordPress already has: your author display name, post title, site name, published date, and permalink. JavaScript formats it into the chosen style (APA, MLA, Chicago, Harvard, or plain link) and copies it to the clipboard. No external API, no account.
Yes. Insert the block in a template using the Template Editor. Auto-insert mode works across any registered public post type.
Typically right after the introduction paragraph, before the first heading. Some writers prefer just before the conclusion. Auto-insert mode handles positioning automatically sitewide.
No. Keep it tocflow — that is the WordPress plugin slug, folder name, and text domain. Naming notes.