=== Mocursor Smart TOC ===
Contributors:      mosescursor
Plugin Name:       Mocursor Smart TOC
Description:       Automatically generates a linked, navigable table of contents from your post headings with smooth scrolling, numbering styles, collapsible display, and shortcode support.
Plugin URI:        https://mosescursor.com/moses-cursor-smart-toc/
Version:           1.0.2
Requires at least: 6.4
Tested up to:      7.0
Stable tag:        1.0.1
Requires PHP:      7.4
Author:            mosescursor
Author URI:        https://mosescursor.com
Donate link:       https://buymeacoffee.com/mocursor
Developer:         mosescursor
Developer URI:     https://mosescursor.com
Documentation URI: https://mosescursor.com/mocursor-smart-toc-documentation/
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:       mocursor-toc


A powerful, lightweight Gutenberg block that automatically generates a linked, navigable table of contents from your post headings.

== Description ==

**Mocursor Smart TOC** is a lightweight, feature-packed Gutenberg block that automatically generates a linked table of contents from the headings in your posts and pages. Simply drop it into your content — it just works. Also available as a `[mctoc]` shortcode for classic editor users.

The block is **fully dynamic**, **accessible**, **lightweight**, and **theme-aware**. It uses WordPress design tokens and CSS custom properties so it inherits your theme's colors, fonts, and spacing automatically.

= Shortcode Support =

The Mocursor Smart TOC block is also available as a `[mctoc]` shortcode for use in the classic editor, widgets, or theme templates.

**Basic usage:**

    [mctoc]

**With options:**

    [mctoc title="On This Page" include_h2="true" include_h3="true" include_h4="false" numbering="nested" collapsed="true" sticky="true" offset="100" skip="1" exclude_headings="Related Posts,Comments" back_to_top="true"]

**Available shortcode attributes:**

* `title` — TOC heading text (default: "Table of Contents")
* `include_h2` — Include H2 headings: "true" or "false" (default: "true")
* `include_h3` — Include H3 headings: "true" or "false" (default: "true")
* `include_h4` — Include H4 headings: "true" or "false" (default: "true")
* `exclude_headings` — Comma-separated heading texts to exclude
* `numbering` — Numbering style: "none", "decimal", or "nested" (default: "none")
* `collapsed` — Start collapsed: "true" or "false" (default: "false")
* `sticky` — Enable sticky mode: "true" or "false" (default: "false")
* `offset` — Scroll offset in pixels for fixed headers (default: 80)
* `skip` — Number of headings to skip from the start (default: 0)
* `back_to_top` — Show "Back to Top" link: "true" or "false" (default: "false")

= Ideal Use Cases =

Mocursor Smart TOC is perfect for:

* **Long-form blog posts** — Help readers navigate 2,000+ word articles with ease.
* **Documentation and knowledge bases** — Technical docs, how-to guides, and reference pages.
* **Online courses and tutorials** — Give learners a clear roadmap of every lesson section.
* **Legal, policy, and compliance pages** — Terms of service, privacy policies, and similar documents.
* **Product and feature pages** — Long product descriptions with multiple sections.
* **Recipe and travel blogs** — Readers can jump to the section they care about.
* **Wiki-style internal sites** — Any WordPress site used as an internal wiki or resource library.
* **Accessibility-focused sites** — The TOC gives keyboard and screen reader users a reliable way to navigate.
* **Classic editor users** — The shortcode works perfectly in the classic editor.

= Why Choose Mocursor Smart TOC? =

1. **Zero configuration needed** — Drop the block in and it works immediately.
2. **100% Gutenberg-native + Shortcode** — Built as a real Gutenberg block with a classic shortcode fallback.
3. **Dynamic and always up to date** — Server-rendered, always matches the current content.
4. **Incredibly lightweight** — No JavaScript frameworks. Pure vanilla JS for all interactivity.
5. **Deeply customizable** — Rich inspector controls for heading levels, numbering, collapsibility, sticky mode, and more.
6. **Accessible by default** — Proper ARIA attributes, keyboard navigation, semantic HTML, and focus management.
7. **Theme-aware** — Uses WordPress design tokens and CSS custom properties.
8. **No lock-in** — Deactivate the plugin and your content is untouched.
9. **Privacy-friendly** — No external requests, no tracking, no analytics, no cookies.
10. **Open source** — Licensed under GPLv2.

= Block Features =

* Automatic heading detection for H2, H3, and H4
* Heading level filtering with individual checkboxes
* Exclude specific headings by text
* Skip first N headings option
* Three numbering styles: None, Decimal, Nested
* Collapsible TOC with configurable default state
* Smooth scrolling with configurable offset
* Active heading highlight via IntersectionObserver
* Back to Top link
* Sticky mode
* Live editor preview
* Full block editor design controls (colors, typography, spacing, borders)
* Shortcode support with full attribute control

= How to Use =

**Method 1: Block Editor**

1. Install and activate the plugin.
2. Open any post or page in the block editor.
3. Click the block inserter (+), search for "Mocursor Smart TOC", and insert the block.
4. Customize via the block settings sidebar.
5. Publish — the TOC renders with smooth scrolling and active heading tracking.

**Method 2: Shortcode**

1. In any post, page, or widget, type `[mctoc]`.
2. Optionally add attributes: `[mctoc title="Contents" numbering="decimal" collapsed="true"]`.

**Method 3: PHP Template**

    <?php echo do_shortcode( '[mctoc title="Page Contents" numbering="nested"]' ); ?>

**Tips:**

* Place the TOC inside a Group block with a max-width for a contained look.
* Enable sticky mode for sidebar layouts.
* Use the shortcode in classic editor widgets or template files.

== Frequently Asked Questions ==

= Does the TOC update automatically when I change headings? =

Yes. The block is dynamically rendered on the server every time the page loads.

= Which heading levels are supported? =

The TOC block supports H2, H3, and H4. Toggle each level on or off independently.

= Can I exclude specific headings from the TOC? =

Yes. In the block settings or via the shortcode `exclude` attribute, provide a comma-separated list of heading texts to omit.

= What happens if there are no headings? =

The TOC block doesn't render anything. No empty box, no broken layout.

= Can I use the shortcode in the classic editor? =

Yes. The `[mctoc]` shortcode works in the classic editor, widgets, and theme templates.

= Does the plugin make any external requests? =

No. Everything runs entirely on your server. Fully GDPR and privacy compliant.

== Screenshots ==

1. The Mocursor Smart TOC block in the editor showing a live heading preview and inspector controls.
2. Frontend rendering with nested numbering, smooth scroll navigation, and active heading highlighting.

== Changelog ==

= 1.0.2 =
* Added `[mctoc]` shortcode support with full attribute control.
* Enqueue frontend assets (CSS and JS) on shortcode usage for classic editor compatibility.

= 1.0.1 =
submitted to the plugins review team and added Documentation and plugin uri

= 0.1.0 =
* Initial release with Table of Contents block.

== Upgrade Notice ==

= 1.0.1 =
Adds shortcode support for the classic editor and widgets. Safe upgrade from 0.1.0.

= 0.1.0 =
Initial release of Mocursor Smart TOC.