Title: Tocnest Table of Contents
Author: adastraconnect
Published: October 28, 2026
Last modified: October 28, 2026
---
Search plugins
# Tocnest Table of Contents
By [adastraconnect](https://profiles.wordpress.org/adastraconnect/)
[Download](https://downloads.wordpress.org/plugin/tocnest.1.0.0.zip)
* [Details](https://wordpress.org/plugins/tocnest/#description)
* [Reviews](https://wordpress.org/plugins/tocnest/#reviews)
* [Installation](https://wordpress.org/plugins/tocnest/#installation)
* [Development](https://wordpress.org/plugins/tocnest/#developers)
[Support](https://wordpress.org/support/plugin/tocnest/)
## Description
Tocnest helps readers find their way through long articles. Add the Tocnest block
in the editor, or let automatic insertion handle your posts. All features are included,
without accounts, license keys or upgrade notices.
#### What makes Tocnest distinct
* **One-click migration and batch post conversion:** Built-in importer for LuckyWP
Table of Contents global settings, lazy runtime compatibility for existing `[
lwptoc]` shortcodes and saved blocks, undo snapshot protection, and a batched
AJAX converter (200 posts per request) for per-post metadata overrides without
modifying post content in the database.
* **Native Gutenberg block with live ServerSideRender preview:** Purpose-built
block (`apiVersion: 3`) with Inspector controls and live server-rendered preview,
plus automatic duplicate suppression when a manual block or shortcode is present.
* **Zero-jQuery, WCAG-accessible semantic `` markup:** Uses semantic `` and nested ``/`` lists, `aria-expanded` and `aria-controls` toggle
state, `aria-current="location"` active section tracking via `IntersectionObserver`,
keyboard focus management, and `prefers-reduced-motion` support. If JavaScript
is disabled, the table of contents stays open and every link works.
* **Deterministic heading ID collision handling:** Preserves existing author heading
IDs across the entire document, reserves IDs across multiple posts rendered in
the same request, supports transliterated or Unicode slugs, and appends deterministic`-
2`, `-3` suffixes on collision.
#### Key features
* Works immediately on posts with at least three h2-h4 headings.
* Automatic placement, a `[tocnest]` shortcode and a classic widget.
* Decimal, nested decimal, Roman and nested Roman numbering.
* Heading filters by level, text, wildcard and CSS class. The `tocnest-skip` class
always excludes a heading.
* Five color schemes, six color overrides, font controls and responsive sizing.
* Smooth scrolling with a sticky-header offset, reduced-motion support and optional
section highlighting.
* Per-post controls in both editors and optional anchors without a visible TOC.
Tocnest only loads its small CSS and vanilla JavaScript when a TOC renders. Tocnest
renders on singular post views. Password-protected posts, excerpts, feeds, public
REST/JSON requests and nested content filters never expose a TOC. The authenticated
block editor preview is supported.
#### Privacy
No data is collected or sent anywhere. Tocnest performs no external requests and
loads no remote assets. Settings and per-post overrides stay in your own database.
Uninstall removes Tocnest settings, import backups and reports, the detection cache
and Tocnest per-post overrides from each site. Previous plugin data and post content
are preserved.
### Migrating from another table of contents plugin
Import settings from the LuckyWP Table of Contents plugin through Settings > Tocnest
> Import. Tocnest is independent and is not affiliated with that plugin or its authors.
1. Make a site backup and open the Import tab. Review detected option groups and post
counts. Counts are capped at 10,001 and cached for five minutes.
2. Click Import settings. General, appearance, automatic insertion, anchor-only post
types and miscellaneous options are mapped. A report identifies unsupported or
unknown values. Compatibility is enabled automatically.
3. Deactivate the previous plugin. Old [lwptoc] shortcodes and saved contents blocks
now render through Tocnest. They are registered only when the previous plugin is
inactive and compatibility is enabled.
4. Per-post settings work lazily without database writes. Optionally choose Convert
per-post settings now to process 200 posts per request with progress. Existing
Tocnest overrides are preserved.
5. Undo import restores the global Tocnest settings from before the first import.
It does not remove converted per-post settings. Repeated imports keep that original
snapshot until you undo.
The old contents block remains editable as a compatibility block. To use the new
Inspector, replace it with a Tocnest block; no editor conversion step is required
for existing content to render. Existing legacy widget instances (id lpwtoc_widget)
are not changed automatically; replace those widgets with the Tocnest block or classic
widget.
While both plugins are active, a notice appears only on this settings page and Tocnest
pauses automatic insertion when the previous auto insertion is enabled. Advanced
settings offers an explicit override.
Mapping details: excluded h1-h6 levels are preserved; depth remains relative nesting
depth. All five numbering styles, three suffixes, five positions and five schemes
map directly. Font weight names map to CSS 100 through 900. Default font sizes become
1em. The rightwithoutflow float becomes a standard right float and div lists become
accessible ul lists. Pipe-separated skip patterns honor escaped pipes and become
one pattern per line. The asheadingwotransliterate anchor format preserves original
characters. Unknown enums fall back to Tocnest defaults. wrapNoindex is unsupported
and reported as skipped. Null or missing per-post values inherit global settings.
### Developers
Filters:
* tocnest_settings ($settings): global settings before shared schema validation.
* tocnest_should_render ($allowed, $post): veto rendering.
* tocnest_headings ($headings): heading records before selection and rendering,
with id, text, level and class keys.
* tocnest_anchor ($anchor, $text, $heading): customize a generated ID before uniqueness
checks.
* tocnest_html ($html): final escaped TOC HTML. Extensions must escape their own
additions.
* tocnest_post_types ($types): automatic insertion post types.
Actions: tocnest_before_render ($post, $settings) and tocnest_after_render ($post,
$settings) run around successful rendering. Use them for integration side effects;
filter tocnest_html to alter output.
## Blocks
This plugin provides 1 block.
* Tocnest An accessible table of contents for this post.
## Installation
1. Upload the tocnest folder to /wp-content/plugins/, or install the ZIP through Plugins
> Add New.
2. Activate Tocnest Table of Contents.
3. Open Settings > Tocnest. Automatic insertion is enabled for posts with at least
three included headings.
4. For manual placement, add the Tocnest block. A manual block or shortcode prevents
automatic duplication in that post.
## FAQ
### What is the recommended way to add a TOC?
Use the Tocnest block. Its Inspector offers the main options and a server-rendered
preview. Save the post to refresh the heading source for its preview. The block
also works in block widget areas.
### Can I use a shortcode?
Yes: [tocnest]. Attributes include min, depth, title, show_title, toggle, collapsed,
numbering, hierarchical, skip_levels, skip_text and class. Use true/false or 1/0
for booleans. For example:
[tocnest min=”2″ depth=”3″ title=”On this page” numbering=”roman” skip_levels=”h4″
class=”article-index”]
All global setting keys can be supplied as shortcode attributes, except automatic
insertion and post-only enable overrides. Shortcodes are independent of the automatic
insertion position. Supply levels as a comma-separated list and skip_text as one
pattern per line. Numbering accepts none, decimal, decimalnested, roman and romannested.
Suffix accepts none, dot and roundbracket.
### Can I override a single post?
Use the Tocnest meta box in either editor to enable or disable the TOC, choose a
position, or change the minimum number of headings. Blank controls inherit the site
settings. More override keys are available through the registered _tocnest_settings
REST meta schema and developer APIs.
### How does depth work?
Depth counts nesting from the first included heading, rather than its h1-h6 number.
An h2 followed by an h4 forms two nesting levels. Excluded headings do not create
empty list items.
### What happens to existing anchors?
Existing heading IDs remain unchanged. Generated IDs reserve existing IDs throughout
the content and add -2, -3 and so on for collisions, including generated anchors
in other posts rendered during the request. Authors should fix any duplicate IDs
already present in their markup. Text anchors transliterate accents by default;
the importer can preserve original characters. Counter anchors use toc-1, toc-2
and so on.
### How can my theme customize the appearance?
Use Settings > Tocnest > Appearance, or override CSS properties such as –tocnest-
background, –tocnest-border, –tocnest-title-color, –tocnest-link, –tocnest-hover
and –tocnest-visited. The container has the tocnest class. Custom widths and font
sizes accept positive px, em, rem, %, vw, vh or ch lengths. Avoid floats on narrow
layouts; Tocnest automatically clears them on small screens.
### Does the plugin change my post content in the database?
No. Anchors and navigation are added only during rendering. Batch conversion creates
Tocnest per-post settings and leaves the previous settings untouched. Deactivation
restores the original content output.
## Reviews
There are no reviews for this plugin.
## Contributors & Developers
“Tocnest Table of Contents” is open source software. The following people have contributed
to this plugin.
Contributors
* [ adastraconnect ](https://profiles.wordpress.org/adastraconnect/)
[Translate “Tocnest Table of Contents” into your language.](https://translate.wordpress.org/projects/wp-plugins/tocnest)
### Interested in development?
[Browse the code](https://plugins.trac.wordpress.org/browser/tocnest/), check out
the [SVN repository](https://plugins.svn.wordpress.org/tocnest/), or subscribe to
the [development log](https://plugins.trac.wordpress.org/log/tocnest/) by [RSS](https://plugins.trac.wordpress.org/log/tocnest/?limit=100&mode=stop_on_copy&format=rss).
## Changelog
#### 1.0.0
* Initial release with automatic insertion, accessible block, shortcodes, widget,
per-post overrides and migration tools.
## Meta
* Version **1.0.0**
* Last updated **1 day ago**
* Active installations **Fewer than 10**
* WordPress version ** 6.3 or higher **
* Tested up to **7.1.4**
* PHP version ** 8.2 or higher **
* Tags
* [accessibility](https://wordpress.org/plugins/tags/accessibility/)[blocks](https://wordpress.org/plugins/tags/blocks/)
[navigation](https://wordpress.org/plugins/tags/navigation/)[shortcode](https://wordpress.org/plugins/tags/shortcode/)
[table of contents](https://wordpress.org/plugins/tags/table-of-contents/)
* [Advanced View](https://wordpress.org/plugins/tocnest/advanced/)
## Ratings
No reviews have been submitted yet.
[Your review](https://wordpress.org/support/plugin/tocnest/reviews/#new-post)
[See all reviews](https://wordpress.org/support/plugin/tocnest/reviews/)
## Contributors
* [ adastraconnect ](https://profiles.wordpress.org/adastraconnect/)
## Support
Got something to say? Need help?
[View support forum](https://wordpress.org/support/plugin/tocnest/)