README

A Modularity module that automatically generates a dynamic, linked table of contents based on headings found on the page. Features a mobile-optimized drawer interface and optional sticky sidebar positioning.

Description

This plugin provides a Table of Contents module for the Modularity plugin ecosystem. It automatically scans the page content and generates a navigable list of headings, making it easier for users to quickly jump to different sections of long-form content.

Features

Automatic Heading Detection: Automatically finds and lists headings from the page content
Customizable Heading Levels: Choose which heading levels (H2, H3, H4) to include in the table of contents
Multiple Container Support: Scans specific content areas including:
- Sidebar content areas
- Article content
- Main content area
Card Display Option: Option to display the TOC inside a styled card component
Smart Card Filtering: Option to ignore headings inside cards except for card headers
Smooth Navigation: Clickable links that navigate smoothly to each section
Active State Tracking: Highlights the current section as users scroll through the page
Configurable Mobile Style: Choose between a collapsible dropdown or always-expanded layout on mobile
Per-instance Visibility Control: Hide the TOC on mobile, desktop, or both per module instance
Sliding Track Indicator: Visual indicator that follows the active section
Sticky Sidebar Support: Option to make the entire sidebar column sticky when TOC is present
Block Compatible: Works as a native Gutenberg block with editable title
Automatic Mobile Insertion: Automatically inject a mobile version of the TOC into any container on the page via CSS selector, without manually placing a second module
Configurable Mobile Breakpoint: Override the default 78em breakpoint via a PHP filter — updates both JS behaviour and injected CSS
Extensible via PHP Filters: Add custom sidebar containers and choices without modifying the plugin
Responsive Design: Works seamlessly across all device sizes with dedicated mobile and desktop UX

Configuration Options

Module Instance Settings

Configure these settings for each individual TOC module instance:

Include headings from following sidebars:

Content area (above article)
Content area (below article)
Main container bottom

Which heading levels to include: Choose from H2, H3, and/or H4 headings (default: H2)
Place in card: Toggle to display the TOC within a card component
Ignore card sub-headers: Option to exclude headings inside cards (except card headers)
Hide on mobile: Hide this TOC instance on mobile devices (below the mobile breakpoint, default 78em / ~1248px)
Hide on desktop: Hide this TOC instance on desktop (at or above the mobile breakpoint, default 78em)

Global Settings

Configure these settings once for all TOC modules (found in Settings > Table of Contents):

Show sliding track: Display a visual sliding track indicator that follows the active section (default: enabled)
Sticky list: Make the entire sidebar column sticky when it contains a TOC module
Automatic mobile insertion: When enabled, a mobile copy of the TOC is automatically injected into the page via JavaScript — no need to place a second module manually. The manually placed module is automatically hidden on mobile when this is active.
- CSS Selector: The target container to inject into (e.g. article, .c-article, #article)
- Insertion method: Where relative to the target the TOC is placed — Prepend to container, Append to container, Before element, or After element
Mobile style: How the TOC is displayed on mobile — dropdown (collapsible, default) or expanded (always visible)

CSS Variables

The module uses the following CSS custom properties that can be customized in your theme:

Sliding Track

--toc-border-width: Width of the track border line (default: 4px)
--toc-track-width: Width of the background track line (default: 4px)
--toc-track-indicator: Color of the active sliding indicator (default: #666)
--toc-track-color: Color of the background track (default: #ccc)
--toc-track-top: Calculated top position of the sliding indicator (set by JS)
--toc-track-height: Calculated height of the sliding indicator (set by JS)

Mobile Dropdown

--toc-mobile-border-color: Border color of the mobile TOC container (default: #d6d6d6)
--toc-mobile-background: Background color of the mobile TOC container (default: #fff)
--toc-mobile-color: Text color inside the mobile TOC container (default: inherit)

General

--base: Base spacing unit (default: 8px)

Example CSS Customization

/* Customize TOC link appearance */
.modularity-mod-toc {
  --toc-link-color: #0073aa;
  --toc-link-color-hover: #005a87;
  --toc-link-font-weight: 500;
}

/* Customize sliding track appearance */
.modularity-mod-toc {
  --toc-border-width: 3px;
  --toc-track-indicator: #0073aa;
  --toc-track-color: #e0e0e0;
}

/* Customize mobile TOC container */
.modularity-mod-toc {
  --toc-mobile-background: #f5f5f5;
  --toc-mobile-border-color: #ccc;
}

Requirements

WordPress
Modularity plugin
Municipio theme (v6.0.0 or higher)
Advanced Custom Fields (ACF) Pro

Installation

Clone or download this repository to your WordPress plugins directory
Run composer install to install dependencies
Run npm install && npm run build to build assets
Activate the plugin through the WordPress admin panel
The "Table of Contents" module will now be available in Modularity

Usage

Edit a page or post where Modularity is enabled
Add a new module and select "Table of Contents"
Configure the module settings according to your needs
Publish or update the page
The table of contents will automatically populate based on the headings found on the page

Mobile Style

Below the mobile breakpoint (default: 78em / ~1248px), the TOC switches to a mobile layout. The style can be configured globally:

Dropdown (default): The TOC content is collapsed behind a toggle button. Clicking it expands/collapses the list in place.
Expanded: The TOC content is always visible on mobile, without a toggle.

Per-instance, you can also hide the TOC entirely on mobile or desktop using the Hide on mobile / Hide on desktop instance settings.

The breakpoint itself can be changed via the Modularity/Module/TableOfContents/MobileBreakpoint PHP filter — see PHP Filters below.

PHP Filters

The plugin exposes two filters for extending sidebar support without modifying the plugin:

`Modularity/Module/TableOfContents/SidebarChoices`

Add custom choices to the "Include headings from following sidebars" ACF field:

add_filter('Modularity/Module/TableOfContents/SidebarChoices', function (array $choices): array {
    $choices['my-custom-sidebar'] = __('My Custom Sidebar', 'my-theme');
    return $choices;
});

`Modularity/Module/TableOfContents/SidebarSelectorMap`

Map custom sidebar keys to their CSS selectors so the JS knows where to scan for headings:

add_filter('Modularity/Module/TableOfContents/SidebarSelectorMap', function (array $map): array {
    $map['my-custom-sidebar'] = '#my-custom-sidebar-element';
    return $map;
});

Both filters must be used together for a custom sidebar to appear in the field and be scanned for headings.

`Modularity/Module/TableOfContents/MobileBreakpoint`

Override the breakpoint at which the TOC switches between its desktop and mobile layouts. The default is 78em (~1248px).

Changing this value affects both the JavaScript behaviour (when the toggle button appears and the change listener fires) and the CSS (override rules are automatically injected via wp_add_inline_style).

Note: The CSS override covers all visual rules gated by the breakpoint. If you also have custom styles that reference 78em, update those separately in your theme.

add_filter('Modularity/Module/TableOfContents/MobileBreakpoint', function (): string {
    return '60em'; // ~960px
});

Development

Build Assets

npm install
npm run build

Development Mode

npm run dev

Watch Mode (rebuild on changes)

npm run watch

Build Development Version (unminified)

npm run build:dev

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Author: Consid Borås AB
Repository: considbrs-webdev/modularity-toc

considbrs-webdev / modularity-toc

Maintainers

Package info

Statistics

Security