Mocursor Smart TOC

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.