Get TOC Genius working
on your WordPress site.
Start with the Free plugin. Use Pro when you need publishing rules, shared templates, or adaptive navigation.
Feature beta release. Evaluate these packages on staging. Automated migration and a commercial Pro service are not part of this release.
Requirements
WordPress 6.5 or newer, PHP 7.4 or newer, and permission to install plugins. Free 0.2.0 or later is required before activating Pro 0.2.0. Update Free first.
Install Free
- Download the Free ZIP.
- In WordPress, open Plugins → Add New → Upload Plugin.
- Choose the ZIP, select Install Now, then Activate.
- Open Settings → TOC Genius.
The initial defaults enable Posts, include H2 and H3 headings, require three eligible headings, and place the TOC before the first heading. Pages and other public content types are opt-in.
Choose your defaults
Choose placement, heading levels, and the minimum count. Appearance includes five presets, width, alignment, spacing, typography, theme-color inheritance, and custom colors. Reader controls include collapse, numbering, current-section highlighting, basic sticky contents, and a header offset.
The appearance preview uses a sample article. Save changes to apply global defaults. Pro templates and rules can override those defaults.
Edit an individual article
Open a post and find its TOC Genius panel. Choose:
- Inherit site settings: follow the site’s automatic placement and threshold.
- Always show automatically: show when at least one eligible heading exists.
- Manual placement only: wait for a block or shortcode in the article body.
- Disable all TOCs: suppress automatic and manual TOCs for that article.
Save the article to refresh the heading list. Use the label inputs to change TOC text without changing the article headings. Exclude headings individually. Existing IDs remain intact; headings without IDs receive collision-safe IDs in the rendered output.
Manual block or shortcode
Insert the TOC Genius block in the block editor, or place [tocgenius] in the article body. The first manual marker replaces automatic insertion. Additional markers are removed. Manual TOCs need at least one eligible heading and remain inline in Pro.
Understand why the TOC appears
In Settings → TOC Genius → Tools, search for an editable article by title (or enter an ID using the manual option) and select Inspect article. Diagnostics show eligible stored headings, their targets, the visibility decision, and—with Pro—the applied template and rule evaluation.
Diagnostics use stored content. A dynamic block or another plugin may generate additional front-end headings later, so verify the published article too.
Install Pro
- Keep Free installed and active.
- Download the Pro ZIP. Upload and activate it through the same WordPress plugin screen.
- Open the Rules, Saved templates, and Advanced navigation tabs in TOC Genius.
Pro starts with no rules or templates. Its navigation setting inherits the Free global layout until you choose another layout.
Ordered rules
Name the rule, enable it, choose All or Any, then add conditions. Search and select categories or tags, or enter their slugs manually. Other conditions use content types such as post or page, title text, or an eligible-heading count. Title matching handles non-English capitalization literally, including ÉCOLE/école. Add overrides for automatic show/hide, minimum headings, layout, and an optional shared template.
The first enabled matching rule wins. Move rules up or down to change priority. A count condition uses eligible headings before rule overrides. This avoids a threshold depending on its own result. Choose Hide automatic contents for a News category rule to hide its automatic TOC. Show requires one eligible heading and bypasses the global automatic switch, selected content-type list and minimum. Per-post Disable, Always show and Manual-only choices, manual blocks/shortcodes and global manual placement take priority. Hide does not remove an explicit manual TOC.
Shared templates
Create a named template from the current global appearance. Templates store appearance only. Assign one to a content type or a rule. Editing that stable template ID updates every assignment. If a content type is temporarily unavailable, its assignment is retained and applies again when that public content type returns.
To export, copy the JSON under Import / export templates. To import, replace it with a schemaVersion 1 export and select Validate and import. Imports update matching IDs and add new IDs. Invalid data is rejected before changes are applied. This appearance-only export does not include rules or assignments.
Undo last import restores the library immediately before the last successful import. It also reverts later template edits. Other valid rules and navigation settings remain; references to removed templates are cleared.
To remove an obsolete template, expand Delete template and confirm. Its assignments are removed and its references in rules are cleared, preserving rule order and other overrides. At the 30-template limit, duplication shows an error; delete a template to make room.
Complete configuration transfer
In Tools → Complete configuration transfer, download or copy JSON. On the destination site, upload the file or paste JSON, select Validate and preview import, review the incoming settings and confirm replacement.
This replaces Free global settings, all templates, ordered rules, assignments and navigation, including empty libraries. Article content, per-post overrides and the destination’s uninstall-cleanup choice stay local. Valid dormant content types are preserved. Files are limited to 256 KB; malformed data, unknown fields and missing references are rejected.
The preview belongs to its administrator, expires after 15 minutes, and cannot replace settings changed since preview. Undo last import restores the pre-import configuration only until a later configuration edit. Supported transactional database storage is required; unsupported storage is rejected before configuration changes.
Adaptive navigation
Choose Adaptive rail / mobile panel as the default or a rule override. The desktop rail appears only when the article has enough clear right-side space. If a sidebar, footer, or other visible content occupies that space, it keeps the contents inline and checks again when the layout changes. On mobile, a contents button opens a nonmodal panel. Search keeps matching sections and their hierarchy. Escape closes the panel, and selecting a section moves focus to its heading.
Switching from another TOC plugin
Version 0.2.0 has no automated migration. Test one article on staging with the old TOC plugin disabled. Confirm the TOC, heading IDs, old bookmarked links, layout, and header offset before switching the rest of the site.
Existing IDs saved in the article are preserved. IDs generated only by another plugin may disappear when that plugin is disabled. Save those IDs into the content or plan a separate migration before switching.
Data and privacy
Both packages run locally. They include no telemetry, license-server request, external assets, or front-end credit links. Deactivation preserves settings. Uninstall also preserves data unless you explicitly enable the Free plugin’s cleanup option.
On multisite, the cleanup choice is evaluated separately for each site. Free uninstall with cleanup enabled also removes its known Pro add-on settings. Uninstalling Pro first uses the same cleanup choice.
Scope and compatibility
TOC Genius reads article-body headings in the WordPress the_content pipeline at priority 20. It avoids feeds, admin pages, REST content, password-protected content, and content outside the main singular loop.
Content produced outside that pipeline, headings added later by page builders, and every theme combination have not been certified. The basic sticky layout keeps a short TOC within the article and places clicked headings below its measured height. A long TOC or short viewport uses inline contents to preserve reading space. Pro’s side rail is progressive and depends on available space.