=== TOC Genius ===
Contributors: pluginsshop
Tags: table of contents, navigation, headings
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.4
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A customizable automatic table of contents with a manual block, existing-anchor preservation, and per-post controls.

== Description ==

TOC Genius creates a table of contents from rendered article headings on singular posts and pages, using the WordPress HTML API and preserving existing heading IDs.

Designed for editors maintaining long articles: keep existing section links, change contents labels without changing heading text, and diagnose missing entries or recover unmatched preferences after an article is revised. These controls are included in Free.

Free features:

* Automatic placement before the first heading, after the first paragraph, or at the article end.
* Heading-level selection and a minimum-heading threshold.
* Five appearance presets, width, alignment, spacing, typography, custom colors, and theme inheritance.
* A manual TOC Genius block and [tocgenius] shortcode.
* Per-post placement, heading exclusions, and independent TOC labels.
* Collapse controls, numbering, section highlighting, header offsets, and basic sticky contents.
* Live Gutenberg outline for unsaved static blocks, heading selection, contents labels, exclusions and a rendered TOC block preview.
* Deliberate stable anchors with collision checks; recover unmatched preferences without silently rewriting old articles.
* Classic Editor fallback with compact saved-heading controls.
* Searchable article diagnostics showing included/omitted headings, reasons, unmatched preferences and effective placement.
* Unsaved-settings protection, reachable Save controls, mobile preview disclosure and custom text/accent contrast feedback.

The separate Pro add-on adds ordered show/hide rules, shared templates, configuration portability, and adaptive navigation. Free has one informational About Pro settings tab; premium implementation is not bundled or locked in Free.

All listed Free features work without an account, payment, time limit, or activation key. Automated migration and page-builder certification are not included. Existing heading IDs are preserved; anchors generated only by another plugin need separate evaluation.

== External services ==

TOC Genius calls no external service or third-party API and sends no article content, settings, visitor information, or usage statistics to any provider. It has no telemetry, licence verification, remote assets, or external account/API-key requirement.

Editor previews and article/category/tag searches use admin-ajax.php on the same WordPress installation, with WordPress authentication, nonces, and capability checks. Requests contain search values or an article ID; previews also send the unsaved title, content, and TOC preferences. Previewing requires permission to edit the article; selectors require manage_options. No request goes to a TOC Genius server.

The block editor saves preferences through the site's existing WordPress REST API; the plugin registers no public REST endpoint. Local WordPress HTML, Options, Post Metadata, Block, Shortcode, and script/style APIs and WordPress-supplied editor packages are used.

Choosing a website link makes a normal browser request to that website. WordPress may separately contact WordPress.org for plugin information, translations, or updates; TOC Genius does not replace or disable these services. This describes the installed plugin, not other plugins, hosting, or the separate website demo.

== Privacy and stored data ==

* Global appearance, placement, and cleanup preferences are stored in the site's tocgenius_settings option.
* Per-article mode, custom TOC labels, and excluded heading IDs are stored in _tocgenius_profile post metadata.
* Normal front-end rendering adds any missing heading IDs to the response only. Deliberate editor actions can save stable heading IDs in the article content; see the FAQ below.
* Editor previews process submitted content on your own site without saving the preview as an article. Article searches return only articles the current user is allowed to edit.
* The plugin sets no cookies and uses neither localStorage nor sessionStorage. Reader controls keep temporary state in the current page; section navigation can update the URL fragment and browser history. WordPress's own login cookies remain in use.
* Deactivation keeps settings and article preferences. Uninstall keeps them too unless the site's explicit Data cleanup option is enabled. Cleanup removes plugin options and article preference metadata, including stored Pro configuration/history when present. It does not delete articles, undo saved heading IDs, remove blocks/shortcodes from article content, or delete exported files.

On multisite, the cleanup choice is evaluated separately for each site. Removing this package preserves shared data on sites where the legacy package remains active. If Pro is installed, its readme documents additional configuration, administrator history, and temporary review data.

== Source code ==

Editable PHP, JavaScript, and CSS source is included in the main file, includes, and assets directories; no compilation, minification, npm, or Composer build is required. WordPress packages are dependencies, not bundled copies. The GPL-2.0-or-later licence is in LICENSE.txt.

For setup help, see the [documentation](https://tocgenius.com/docs.html) or [support centre](https://tocgenius.com/help/).

== Installation ==

1. Upload the toc-genius folder to wp-content/plugins or upload the ZIP through Plugins > Add New > Upload Plugin.
2. Activate TOC Genius.
3. Open Settings > TOC Genius.
4. Review a staging article with at least three H2/H3 headings.

Posts are enabled by default; Pages and other public content types are opt-in. For manual placement, insert the TOC Genius block or [tocgenius] in the article body.

== Frequently Asked Questions ==

= Does it rewrite stored content? =
Normal front-end rendering does not rewrite stored articles. Gutenberg can add a missing stable ID to a core Heading block when you change its TOC label/exclusion, reassign preferences, or deliberately stabilize links and then save. Classic Editor can stabilize eligible headings throughout the article when those heading controls or the stabilization choice are saved. Existing explicit IDs are preserved and collisions are reported. The custom TOC label changes the contents entry, not the article's visible heading text. Uninstall does not undo IDs saved in article content.

= What if existing IDs are duplicated? =
Those headings are excluded from the TOC and a diagnostic asks you to fix the duplicate IDs.

= What if a manual block and automatic insertion both exist? =
The manual block or shortcode owns the TOC. Only the first manual marker is used. The per-post Disable all TOCs setting suppresses both.

= Does it support every page builder? =
It parses headings in the final article HTML at the_content priority 20. Content outside that pipeline or generated later by another component may require integration work. No page-builder compatibility claim is made for this release.

= What happens when I uninstall? =
Deactivation preserves data. Before uninstalling, enable Settings > TOC Genius > Data cleanup only if you want plugin settings and article preference metadata removed. This also removes the site's stored Pro configuration, pending reviews, recovery history, and drafts when present. Articles, saved heading IDs, and manually inserted blocks/shortcodes remain. On multisite, cleanup is opt-in separately for each site.

= Moving from the older tocgenius folder? =
The WordPress.org package uses toc-genius/tocgenius.php. It keeps existing options, article preferences, blocks and shortcodes. Back up first. In the old plugin, turn Delete plugin data on uninstall OFF, save and reload to verify it on every site. Deactivate Pro, then the old Free package without deleting it. Install/activate the new Free package, then update/activate matching Pro 1.1.4. Check saved settings and articles before removing only the inactive old tocgenius folder over SFTP; this skips uninstall. WordPress Delete is safe only after verifying cleanup remains OFF on every site. See bundled migration.txt for limits and recovery.

= How do I update the plugin? =
For an existing toc-genius installation, back up and test on staging. In Plugins > Add New > Upload Plugin, upload Free and choose Replace current with uploaded; repeat with matching Pro if used. Replacement preserves settings. Do not uninstall to update: opted-in cleanup removes data. Pro export/history excludes articles and is not a database backup. Pro has no automatic updater in this release.

== Screenshots ==

1. Settings and appearance controls (Free 0.4.3; fictional sample content).
2. Gutenberg article controls for placement, section links, labels and exclusions (Free 0.4.3; fictional article).
3. Article diagnostics explaining included and omitted headings (Free 0.4.3; fictional article).

== Changelog ==

= 1.1.4 =
* Validate the appearance preview of rejected Pro settings drafts while preserving editable form values.
* Match the Free and Pro release versions; security and configuration guards are unchanged.

= 1.1.3 =
* Retain request nonce type checks and harden automatic placement against unavailable bookmark spans.
* Keep editor previews working without the optional PHP ctype extension.

= 1.1.2 =
* Publish matching Free and Pro 1.1.2 packages. Preserve existing features, data and compatibility requirements.


= 0.4.5 =
* Match the WordPress.org assigned toc-genius slug and translation domain.
* Keep existing data and public content identifiers; guard legacy-package activation and removal.

= 0.4.4 =
* Update the plugin author website to https://plugins.shop/. No feature or settings changes.

= 0.4.3 =
* Publish the release with current documentation and matching Free and Pro version metadata.

= 0.4.2 =
* Fix explicit uninstall cleanup of stored Pro drafts after persistent object caching is enabled.
* Refresh translation documentation and add repository screenshot descriptions.

Earlier release history is available in the [release notes](https://tocgenius.com/release-notes.html).

== Upgrade Notice ==

= 1.1.4 =
Prevent a warning when previewing rejected Pro settings. Replace Free first, then matching Pro, without uninstalling.

= 1.1.3 =
Harden request validation and compatibility. Replace Free first and then Pro, if used, without uninstalling. Existing settings are retained.

= 1.1.2 =
Back up first. Replace Free first, then matching Pro without uninstalling. Existing canonical-folder installations need no folder migration. Saved data is retained.


= 0.4.5 =
The folder is now toc-genius. Follow the migration instructions above for older tocgenius installations; do not uninstall with cleanup enabled. Use matching Pro 1.1.4.
