Understanding Easy Table of Contents Compatibility with Page Builders and Gutenberg

Many WordPress users rely on page builders like Gutenberg, Beaver Builder, and Oxygen to design their content. A common question that arises is whether the popular 'Easy Table of Contents' plugin is compatible with these tools. This guide explains how the plugin interacts with various editors and builders, helping you set it up successfully on your site.

How Easy Table of Contents Works with Editors

The primary function of Easy Table of Contents is to automatically scan the standard WordPress post content field for headings (H1, H2, H3, etc.) and generate a table of contents from them. Its compatibility with any page builder—be it Gutenberg or a third-party option—depends entirely on one key factor: where the builder saves the heading text.

If a page builder stores the finished content, including all headings, in the main post_content field in the WordPress database, Easy Table of Contents should be able to see those headings and generate a TOC without any issues. This is the case for the Gutenberg editor; the plugin's developer has confirmed it works with Gutenberg daily, though it does not use a dedicated block.

Common Compatibility Questions Answered

Is it compatible with Gutenberg?

Yes. The plugin works with the Gutenberg block editor. It automatically inserts the table of contents by processing the headings found in the post content. A dedicated Gutenberg block has been discussed by the plugin's team and is a known feature request, but it is not required for the plugin's core functionality to work.

What about Beaver Builder or Oxygen Builder?

Compatibility is not guaranteed and depends on the builder. The general rule is: if the builder saves the visible page content to the standard post_content field, it will likely work. If the builder stores content in a separate, custom field, the plugin may not be able to detect the headings. The Easy Table of Contents team has not officially added specific support for these builders, so testing in your environment is necessary.

Does it work with other platforms like Shopify or AMP?

No. The Easy Table of Contents team has confirmed they do not offer an equivalent app for the Shopify platform. Regarding AMP (Accelerated Mobile Pages), the plugin is not explicitly tested for compatibility with AMP plugins. You would need to conduct your own tests to see if it functions correctly.

What about Multisite (WPMS) installations?

While the plugin developer has stated it has not been extensively tested on WordPress Multisite, there is no inherent reason it should not work. However, adding dedicated support for Multisite is considered a low priority if issues arise.

Troubleshooting Auto-Insert Problems

The most frequent compatibility issue is the TOC failing to auto-insert on a page. This is often caused by a conflict with another plugin or theme that alters how content is saved or output on the front end.

For example, a user reported that auto-insert stopped working when used alongside the 'Grow Social Pro by Mediavine' plugin after a specific update to Easy Table of Contents. This indicates a plugin conflict.

How to diagnose and fix these issues:

1. Test for a Theme Conflict: Temporarily switch your theme to a default WordPress theme like Twenty Twenty-Four. If the TOC appears, the issue is with your theme.
2. Test for a Plugin Conflict: Deactivate all other plugins except Easy Table of Contents. If the TOC works, reactivate your plugins one by one to identify which one is causing the conflict.
3. Use the Shortcode: If auto-insert is problematic, a reliable workaround is to disable the auto-insert feature in the plugin's settings and manually place the [ez-toc] shortcode in your post or page content where you want the TOC to appear. This method often works regardless of page builder compatibility.

By understanding how the plugin operates and systematically testing for conflicts, you can successfully integrate a table of contents into your builder-designed pages.