TOCguide

Description

TOCguide adds a Table of Contents block to the WordPress block editor. It is an independent plugin by Matt Hummel and is not affiliated with any other company or plugin. Optional Reading Guide mode turns the outline into a reading companion (section previews, read time, progress). Every feature is rendered server-side or handled in the browser with no external API calls, no accounts, and no tracking.

Standard TOC features

• Standard Gutenberg block (block.json, live editor preview, Block Styles)
• Choose H1–H6 heading levels
• Numbered or bulleted lists, including nested 1.1.1 numbering
• Five style presets: Default, Minimal, Boxed, Underline, Card
• Show or hide the title; render it as a paragraph or H2–H4
• Smooth scroll with a configurable offset for sticky headers
• Collapsible outline and optional sticky positioning
• Scroll-spy highlights the section currently in view
• Hide bullets, two-column layout, compact spacing, max height with scroll
• Auto-generate the block sitewide (top of content or after first heading)
• [tocguide] shortcode for classic content and theme templates
• Skip a heading with the CSS class no-toc
• Accessible <nav> landmark with ARIA labels
• Optional ItemList JSON-LD schema markup
• No account, no external API calls, no tracking

Reading Guide mode

Enable Reading Guide in the block sidebar to transform the TOC into a live reading companion. Every enrichment is computed from your block content — no JavaScript fetches, no third-party services.

Section content previews — The opening sentence of every section appears beneath its TOC link, extracted server-side from your block content. Readers scan the outline and know exactly what they are about to read before they click.

Content density bars — A subtle bar under each item shows that section’s word count as a proportion of the longest section. Readers see at a glance which sections are brief and which are deep dives.

Per-section read-time estimates — Word count divided by average reading speed gives a ~N min badge next to each link. Readers can decide what to read and how long it will take.

Reading progress — As a reader scrolls past each section, its TOC item fades out. The outline becomes a live checklist of what has been read and what remains.

Author section notes — Write a short teaser or hook for any section directly in the block editor’s Section Notes panel. Readers reveal it with a single tap (✍ button). The note is stored in block attributes — no database round-trip.

Emoji reactions — Readers react to individual sections (💡 Insightful · ⭐ Saved · 🤔 Unclear · ✅ Got it) with a single click. Choices are stored in the browser’s localStorage. No accounts, no server calls, no tracking.

Per-section academic citations — A § button on each TOC item copies a fully formatted academic citation for that specific section. Five formats supported: APA, MLA, Chicago, Harvard, and plain link. Citation data comes entirely from WordPress post meta (author, title, site name, published date, permalink). Ideal for research blogs, documentation sites, and long-form journalism.

Compatibility

TOCguide is designed to work with every major WordPress stack:

• Theme builders: Gutenberg (native block), Elementor, Divi, Beaver Builder, Bricks Builder, WPBakery, Oxygen, Breakdance — use [tocguide] in any shortcode/HTML element.
• SEO plugins: Yoast SEO, Rank Math, All in One SEO, SEOPress — schema markup is opt-in and off by default; no conflicts with any SEO plugin’s TOC schema output.
• Themes: Works with any theme — inherits theme fonts and colors; no injected brand styles; tested on Twenty Twenty-Four, Twenty Twenty-Five, Astra, Kadence, GeneratePress, Blocksy.
• Multilingual: WPML, Polylang, TranslatePress — fully translation-ready with the standard tocguide text domain.
• PHP: 7.4, 8.0, 8.1, 8.2, 8.3.
• WordPress: 6.4 – 7.1 (tested on all major releases in this range).

Source and development

Unminified JavaScript and SCSS ship in src/. Compiled assets are in build/. From the GitHub repo: npm install && npm run build. Node 20+ (see .nvmrc). PHP coding standards: composer install && composer phpcs.

This plugin does not load JavaScript or CSS from a third-party CDN. Front-end assets are enqueued from files inside the plugin. The GitHub Pages marketing site may load a webfont; that is not part of the plugin zip.

Third-party services

None. TOCguide does not call remote APIs, does not require an account, and does not send data off-site. Details: https://github.com/matthummel-pa/tocguide/blob/main/PRIVACY.md

Privacy

No personal data collection, no marketing cookies, no phone-home. Settings live in the tocguide_settings option. Uninstall deletes data only if you opted in under Settings → TOCguide. Deactivate does not delete settings. Optional JSON-LD is off by default. Study tools that use localStorage stay on the visitor’s device.

Credits on the front end

TOCguide does not print a “powered by” or credit link on published posts.

How to use

1. Edit a post that contains Heading blocks.
2. Insert the Table of Contents block (typically after the introduction).
3. Optionally open the Reading Guide panel in the block sidebar to enable any of the reading companion features.
4. Open Settings → TOCguide to auto-generate the block sitewide or set a scroll offset.

Shortcode

[tocguide]

Layout & behavior: title, showtitle, titletag, h1–h6, ordered, numbering, markers, collapsible, collapsed, sticky, compact, columns, underline, highlight, maxheight, min, smooth, style.

Reading Guide: preview="1" (hover tooltip on links), guide="1" (full Reading Guide mode), previews="1", density="1", readtime="1", progress="1", reactions="1", citations="1", citation="apa|mla|chicago|harvard|plain".

Study assistant: rprogress="1" (document progress bar), bookmark="1" (resume last heading), rnotes="1" (private reader note pads).

Examples:

[tocguide title="On this page" style="boxed" preview="1"]

[tocguide guide="1" previews="1" readtime="1" reactions="1" citations="1"]

Skip a heading

Add the CSS class no-toc or tocguide-skip to a Heading block (Advanced → Additional CSS class(es)).

Support

Documentation and support: https://matthummel-pa.github.io/tocguide/
Issues: https://github.com/matthummel-pa/tocguide/issues

License

TOCguide is copyright 2026 Matt Hummel and licensed under the GNU General Public License, version 2 or later. That license covers the whole plugin (PHP, JavaScript, CSS, and images). The full text is in license.txt.

Technical details