Enjoying these plugins? ☕ Buy me a coffee to support ongoing development.

Simple Table of Contents

A lightweight WordPress plugin that automatically generates and inserts a table of contents based on headings (H2, H3, etc.) in your content, with smooth scroll navigation.

Single File v1.0.0 Updated 1 month ago
View on GitHub Download

YT Simple Table of Contents

A lightweight WordPress plugin that automatically generates and inserts a table of contents based on headings (H2, H3, etc.) in your content, with smooth scroll navigation.

Features

  • Automatic TOC Generation: Detects H2-H6 tags in content and builds a hierarchical table of contents
  • Auto-Insert or Shortcode: Automatically inject TOC before the first heading or use [toc] shortcode
  • Customizable Heading Levels: Choose which heading levels (H2-H6) to include
  • Smooth Scroll Navigation: Click TOC links to smoothly scroll to headings
  • Active Link Highlighting: Automatically highlights the current section in TOC while scrolling
  • Flexible Display Options: Set minimum headings required and choose post types
  • Custom Title: Configure the TOC title text
  • Responsive Design: Mobile-friendly with dark mode support
  • Accessible: Keyboard navigation and screen reader friendly
  • WPCS Compliant: Follows WordPress coding standards with proper sanitization and escaping

Installation

  1. Upload the yt-simple-table-of-contents folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Configure settings at Settings → Table of Contents
  4. The TOC will automatically appear on posts and pages with sufficient headings

Usage

Automatic Display

By default, the plugin will automatically insert the table of contents before the first heading if:

  • The content has 3 or more headings (configurable)
  • The post type is enabled (posts and pages by default)
  • Auto-insert is enabled in settings

Manual Shortcode

Use the [toc] shortcode to manually insert the table of contents anywhere in your content:

[toc]

With custom attributes:

[toc title="Contents" levels="2,3,4"]

Shortcode Parameters:

  • title - Custom title for the TOC (default: "Table of Contents")
  • levels - Comma-separated heading levels to include (e.g., "2,3,4")

Settings

Navigate to Settings → Table of Contents to configure:

Display Settings

  • Enable TOC: Toggle table of contents functionality on/off
  • Auto Insert: Automatically insert TOC before first heading
  • Minimum Headings: Number of headings required to show TOC (default: 3)
  • Heading Levels: Select which heading levels (H2-H6) to include in TOC
  • TOC Title: Custom title displayed above the table of contents
  • Smooth Scroll: Enable smooth scroll animation when clicking TOC links
  • Post Types: Choose which post types should display the TOC

How It Works

Heading Detection

The plugin scans your content for heading tags (H2-H6) and:

  1. Extracts heading text and level
  2. Generates unique IDs for each heading
  3. Builds a hierarchical list structure
  4. Injects IDs into heading tags for anchor linking

TOC Structure

  • H2 headings: Numbered list (1, 2, 3...)
  • H3 headings: Nested alphabetical list (a, b, c...)
  • H4+ headings: Further nested lists

Smooth Scroll

When enabled, clicking a TOC link will:

  1. Smoothly scroll to the target heading
  2. Account for fixed headers (like WordPress admin bar)
  3. Update the URL hash for sharing
  4. Set focus to the heading for accessibility

File Structure

yt-simple-table-of-contents/
├── class-yt-simple-table-of-contents.php  # Main plugin file (~750 lines)
├── assets/
│   ├── css/
│   │   └── yt-simple-toc.css              # Frontend styles
│   └── js/
│       └── yt-simple-toc.js               # Smooth scroll functionality
└── README.md                               # This file

Prefix Convention

All functions, classes, and elements use the yt_simple_toc prefix:

  • Class: YT_Simple_Table_Of_Contents
  • Constants: YT_SIMPLE_TOC_*
  • Functions: yt_simple_toc_*
  • CSS Classes: .yt-simple-toc-*
  • Options: yt_simple_toc_options
  • Text Domain: yt-simple-table-of-contents

Styling

Default Styles

The plugin includes default styles with:

  • Light gray background with blue accent border
  • Responsive design for mobile devices
  • Print-friendly styles
  • Dark mode support

Custom Styling

Override default styles by adding CSS to your theme:

.yt-simple-toc-wrapper {
    background: #your-color;
    border: 1px solid #your-border-color;
}

.yt-simple-toc-link {
    color: #your-link-color;
}

.yt-simple-toc-link:hover {
    color: #your-hover-color;
}

JavaScript Functionality

The included JavaScript provides:

  • Smooth Scroll: Animated scrolling to headings
  • Active Link Highlighting: Current section highlighted in TOC
  • Fixed Header Detection: Adjusts scroll offset for sticky headers
  • Accessibility: Keyboard navigation and focus management
  • Performance: Throttled scroll events for smooth performance

Security Features

  • Capability checks (manage_options)
  • Input sanitization (sanitize_text_field, absint)
  • Output escaping (esc_html, esc_url, esc_attr)
  • Nonce verification for settings forms
  • Safe regex patterns for heading detection

Browser Support

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • Mobile browsers (iOS Safari, Chrome Mobile)

Accessibility

  • Semantic HTML5 structure
  • Keyboard navigation support
  • Focus management for clicked links
  • ARIA-friendly markup
  • Screen reader compatible

Uninstallation

When the plugin is deleted via WordPress admin:

  1. All plugin options are removed
  2. WordPress cache is flushed
  3. No data is left behind

Note: Heading IDs remain in your content but do not affect functionality.

Requirements

  • WordPress 5.8 or higher
  • PHP 7.4 or higher
  • JavaScript enabled in browser (for smooth scroll)

Complexity

  • Main PHP File: ~750 lines (with comments)
  • CSS File: ~130 lines
  • JS File: ~200 lines
  • Total: ~1,080 lines across all files

FAQ

Why isn't the TOC appearing?

Check that:

  1. The plugin is activated
  2. You have enough headings (default: 3 minimum)
  3. Your post type is enabled in settings
  4. Auto-insert is enabled or you're using the [toc] shortcode

Can I change the TOC position?

Yes! Disable auto-insert in settings and use the [toc] shortcode to place it wherever you want.

Does it work with page builders?

The plugin works best with standard WordPress content. Some page builders may require using the [toc] shortcode directly in their content blocks.

Can I exclude specific headings?

Currently, the plugin includes all headings at the selected levels. To exclude a heading, you would need to change its tag (e.g., from H2 to H5 if only H2-H3 are enabled).

License

GPL v2 or later

Author

Krasen Slavov

Support

For issues and feature requests, please visit the GitHub repository.

Changelog

1.0.0

  • Initial release
  • Automatic TOC generation from H2-H6 headings
  • Smooth scroll navigation
  • Active link highlighting
  • Configurable display options
  • Responsive design with dark mode support

Related Plugins