WP Manifestindependent plugin directory
manifest / content / nice-toc-beautiful-table-of-contents-for-wordpress

Nice TOC – Beautiful Table of Contents

Automatically builds a clean, collapsible table of contents from your H1–H6 headings. Inherits your theme's fonts and colors so it always matches your site. Extendable via settings, a shortcode, and filter hooks.

by Muhammad Mehdi · github.com/smy-solutions/nice-toc-beautiful-table-of-contents-for-wordpress · website

★ 2stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/smy-solutions/nice-toc-beautiful-table-of-contents-for-wordpress/archive/refs/heads/main.zip
Readme github.com/smy-solutions/nice-toc-beautiful-table-of-contents-for-wordpress ↗

Nice TOC automatically generates a clean, modern, and collapsible Table of Contents for your WordPress posts, pages, and custom post types. It automatically inherits your active theme's typography, color schemes, and styles so it natively blends into any website design without requiring custom CSS.

✨ Features

  • 🎨 Native Theme Styling: Dynamically uses your theme's fonts and color palette (theme.json color presets) with modern CSS fallbacks (color-mix, CSS custom properties).
  • 🏷️ Smart Heading Extraction: Scans headings (H1–H6) and automatically generates clean, unique anchors while respecting existing heading id attributes.
  • 📍 Flexible Placement:
    • Automatically right before the first heading.
    • Automatically at the very top of post content.
    • Manually via [nice_toc] shortcode.
  • 📂 Collapsible Accordion: Allow users to toggle TOC visibility with customizable initial state (open or collapsed by default).
  • 🔢 Hierarchical & Numbered Formatting: Supports nested bullet lists or auto-numbered structures (1, 1.1, 1.2, etc.).
  • 🎯 Smooth Scroll & Active Section Highlighting: Uses lightweight IntersectionObserver to highlight current sections as readers scroll through the content.
  • 🚫 Heading Exclusion: Add class="toc-exclude" (or your custom class) to skip specific headings from appearing in the TOC.
  • ⚡ Lightweight & Fast: Zero external library dependencies (no jQuery required). Clean single-file design.
  • ⚙️ Post Type Filtering: Select which public post types (Posts, Pages, etc.) display the TOC.

🚀 Installation

  1. Download or clone this repository.
  2. Compress the plugin folder into a .zip archive or copy the nice-toc directory into /wp-content/plugins/.
  3. Go to WordPress Admin > Plugins > Installed Plugins and click Activate under Nice TOC – Beautiful Table of Contents.
  4. Navigate to Settings > Nice TOC to configure your preferred options.

💡 Usage

Automatic Insertion

By default, Nice TOC will automatically insert the Table of Contents right before the first heading in eligible posts when at least 2 headings are present.

Manual Insertion (Shortcode)

Insert the shortcode anywhere within your post or page content where you want the table of contents to appear:

[nice_toc]

Exclude Specific Headings

To exclude a heading from appearing in the Table of Contents, simply add the toc-exclude class (or your custom configured class) to the heading tag:

<h2 class="toc-exclude">This Heading Will Be Skipped</h2>

⚙️ Configuration Options

Go to Settings > Nice TOC in your WordPress dashboard to customize:

Setting Description Default
TOC Title The heading displayed at the top of the TOC box Table of Contents
Heading Levels Select which heading tags to include (H1–H6) H2, H3, H4
Placement Position auto-insertion (Before first heading, Top of content, Shortcode only) Before first heading
Minimum Headings Minimum number of headings required to render TOC 2
Collapsible Enables expandable/collapsible details wrapper Enabled
Collapsed by Default Keeps the TOC closed initially when page loads Disabled
Numbered List Display hierarchical numbered ordering Disabled
Smooth Scrolling Enable smooth scrolling animation upon clicking links Enabled
Highlight Active Highlight section links as user scrolls down page Enabled
Post Types Select public post types to target post
Exclude Class CSS class used to skip specific headings toc-exclude

📂 File Structure

nice-toc/
├── CHANGELOG.md   # Release notes following Keep a Changelog & SemVer
├── composer.json  # Package configuration & Semantic Versioning metadata
├── nice-toc.php   # Main plugin file containing PHP logic, inline CSS, and JS
├── readme.txt     # WordPress.org plugin repository directory text file
└── README.md      # GitHub repository documentation

📌 Versioning

This project strictly adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH):

  • MAJOR: Incompatible API or structural breaking changes.
  • MINOR: Backward-compatible new functionality or feature additions.
  • PATCH: Backward-compatible bug fixes or minor adjustments.

For release history and details, please see the CHANGELOG.md.

🔒 License & Credits