=== Tocnest Table of Contents ===
Contributors: adastraconnect
Tags: table of contents, navigation, accessibility, shortcode, blocks
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

Fast, accessible tables of contents with a native block, automatic insertion, shortcodes, widgets and a settings importer.

== 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 `<nav>` markup:** Uses semantic `<nav>` and nested `<ol>`/`<ul>` 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.

== 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.

== Frequently Asked Questions ==

= 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.

== 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.

== Screenshots ==

1. A real article with nested, accessible Tocnest navigation.
2. General settings, including heading selection and numbering.
3. Migration detection and conversion controls.

== Changelog ==

= 1.0.0 =
* Initial release with automatic insertion, accessible block, shortcodes, widget, per-post overrides and migration tools.

== Upgrade Notice ==

= 1.0.0 =
First release. Review Settings > Tocnest after activation or import.
