How to Exclude Headings by CSS Class from Your Easy Table of Contents

Many WordPress users of the Easy Table of Contents plugin encounter a common issue: unwanted headings from dynamic content, page builders, or other plugins appearing in their automatically generated table. The built-in "Exclude by Text" feature isn't always practical, especially when dealing with content that changes or is generated automatically.

This guide explains the most effective solution: using a custom PHP filter to exclude headings based on their CSS class.

Why Excluding by Class is Necessary

The native settings in Easy Table of Contents allow you to exclude headings by their text content. However, this method falls short for several scenarios:

• Dynamically generated content: Headings from plugins like WooCommerce, recipe cards, or form builders often have text that changes on every page.
• Page builder elements: Themes and builders like Elementor or Divi may inject headings with consistent classes but different text.
• Reusable components: If you use the same component across multiple pages, you want to exclude its heading by a single, stable identifier (a class), not by manually entering every possible text variation.

The Solution: Using the ez_toc_exclude_by_selector Filter

Fortunately, the Easy Table of Contents plugin provides a powerful filter hook, ez_toc_exclude_by_selector, for developers and advanced users. This filter allows you to specify CSS selectors; any heading that matches these selectors will be omitted from the table of contents.

Step-by-Step Implementation

Warning: This solution involves adding custom code to your website. Always back up your site before proceeding.

1. Identify the CSS Class: Use your browser's inspector tool to examine the heading you want to exclude. Find the class name assigned to it. For example, a WooCommerce product title might have the class woocommerce-loop-product__title.
2. Add the Code Snippet: You need to add the following PHP code to your website. The safest way to do this is by using a code snippet management plugin like "Code Snippets." Alternatively, you can add it to your child theme's functions.php file.

/**
 * Exclude headings with a specific CSS class from TOC
 */
add_filter( 'ez_toc_exclude_by_selector', function( $selectors ) {
    // Add your CSS selector(s) here. Prefix class names with a period.
    $selectors[] = '.your-custom-class-here';
    $selectors[] = '.another-class-to-exclude';
    
    return $selectors;
});

3. Customize the Code: Replace .your-custom-class-here with the actual class name you identified in step 1. For example, to exclude the WooCommerce product title, you would use:

$selectors[] = '.woocommerce-loop-product__title';

4. Save and Test: Save the code snippet and clear any caching on your site. Refresh a page with a table of contents to confirm the heading with that class is now excluded.

Example Use Cases from the Community

• WooCommerce: Exclude product titles in loops using .woocommerce-loop-product__title.
• WP Recipe Maker: Exclude recipe names using .wprm-recipe-name.
• Ninja Forms: Exclude template script tags that are mistaken for headings.
• Page Builders: Exclude headings within specific containers (e.g., .et_bloom_below_post for Elegant Themes' Bloom plugin).

Troubleshooting Common Problems

• Code doesn't work: Double-check that you've prefixed your class name with a period (.) and that the class name is spelled correctly. Ensure the code snippet is active and there are no syntax errors.
• It stopped working after an update: While rare, plugin updates can sometimes change how filters work. The ez_toc_exclude_by_selector filter has been the consistent, recommended method for years, but it's good to verify it's still functioning after a major plugin update.
• Shortcode vs. Auto-insert: This filter works for both automatically inserted tables of contents and those generated via the [ez-toc] shortcode.

By leveraging this filter, you gain precise control over what appears in your table of contents, ensuring a clean and relevant experience for your readers.