Identity
PHP, CSS, block tocguide/table-of-contents, shortcode [tocguide], option tocguide_settings.
WordPress plugin · slug tocguide · v1.5.0
Lightweight, server-rendered Table of Contents block for the WordPress block editor (Gutenberg). TOCguide auto-builds an accessible, SEO-friendly linked outline from your post headings — numbered or bulleted, no configuration required. Independent plugin. Not affiliated with any other product.
Optional Reading Guide adds section previews, read-time, hover tooltips, emoji reactions, and one-click citations. All in the first HTML response. No accounts. No tracking. No external APIs.
What's new
Display name TOCguide. Slug, text domain, block, shortcode, CSS, and GitHub repo are all tocguide. Independent plugin — not affiliated with any other product.
PHP, CSS, block tocguide/table-of-contents, shortcode [tocguide], option tocguide_settings.
Re-insert the block and re-save Settings if you used an earlier zip. Old keys are not migrated.
Guideline 17: a coined name that does not imply affiliation. Five tags. GPLv2 or later. No tracking.
Sitewide colours, type, borders, and focus rings that actually print on the <nav>.
Progress bar, resume bookmark, reader notes — all opt-in, all on-device.
Previews, density, citations, and page-builder headings. Still the feature most people come for.
What it does
Insert the block. Get a linked outline from your headings. Accessible <nav>, SEO-friendly, numbered or bulleted — built on Gutenberg, no extra services.
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.
[tocguide] 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".
TOCguide 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 → TOCguide 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
TOCguide 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.
[tocguide] shortcodeUse [tocguide] in any Shortcode, HTML, or Code element. TOCguide automatically reads headings from each builder's stored data and injects matching anchor IDs into the rendered page — no manual slug mapping needed.
[tocguide] in Code module[tocguide][tocguide] works everywheretocguideFound 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 tocguide-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/tocguide, then npm install && npm run build. Source in src/, output in build/.
Frequently asked
Yes — use the [tocguide] shortcode in classic post content, text widgets, or theme templates via do_shortcode('[tocguide]').
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. TOCguide is fully translation-ready with a standard tocguide 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. It is an independent plugin by Matt Hummel. Display name TOCguide, slug tocguide. That naming answers WordPress.org guideline 17 (trademarks / implied affiliation).
GitHub, GitHub Pages, the WordPress.org slug, plugin folder, text domain, PHP prefixes, CSS classes, and the block name are all tocguide. Naming notes.