How to Manually Position the Easy Table of Contents Shortcode in Your Theme

Many WordPress users choose the Easy Table of Contents plugin for its flexibility, including the ability to manually place the table of contents using the [ez-toc] shortcode. However, a common challenge arises when trying to use this shortcode outside of the main post content, such as directly in a theme template file. Users often report issues like the TOC not appearing, a white screen of death, missing CSS styling, or broken anchor links.

This guide explains why these problems occur and provides the correct methods for manually integrating the TOC into your theme.

Why Using do_shortcode('[ez-toc]') Can Cause Problems

The primary issue is one of context. The do_shortcode() function executes the shortcode immediately, but the Easy Table of Contents plugin is designed to perform several important checks and actions during the the_content filter. When you call the shortcode from a theme template (e.g., single.php or page.php), it runs outside of this expected context, leading to several potential failures:

• Plugin Eligibility Checks Fail: The plugin may not be able to determine if the current post is eligible for a TOC (e.g., if the post type is enabled), which can prevent it from rendering.
• CSS/JS Files Not Loaded: The plugin typically enqueues its necessary stylesheets and scripts when it knows it will be displayed on a page. An out-of-context shortcode call can bypass this, leaving the TOC unstyled.
• Anchor Links Don't Work: The JavaScript that handles the smooth scrolling to anchors is often tied to the TOC being generated within the main content flow.
• Fatal Errors (White Screen): In some cases, the plugin functions may be called before they are fully loaded or with incorrect parameters, causing a PHP error that halts page execution.

The Correct Way to Manually Insert the TOC

Instead of using do_shortcode(), the recommended method is to use the dedicated functions provided by the Easy Table of Contents plugin. This ensures all eligibility checks are performed and assets are loaded correctly.

Step 1: Configure Plugin Settings
First, navigate to Settings > Table of Contents. Ensure that the TOC is enabled for your desired post type (e.g., "Posts"). However, you must disable the "Auto Insert" option for that post type. This prevents the plugin from automatically inserting a TOC in the content, allowing you to take full manual control without duplication.

Step 2: Use the Plugin's PHP Function in Your Theme
Within your theme template file (e.g., single.php), use the following code to output the TOC exactly where you want it:

This function is designed to be called directly from theme templates. It handles the internal checks, generates the TOC, and ensures the required CSS and JavaScript are properly enqueued.

Alternative: Using a Custom Function with the_content Filter

If your goal is to insert the TOC at a specific point within the post content itself (e.g., before the second H2 heading), you can use a custom function on the the_content filter. This method keeps the TOC within the content's context.

Important Note: The the_content filter can be applied multiple times on a single page by various plugins. If you add a custom function like the example below, you may see it run more than once. This is not necessarily a bug in Easy Table of Contents but standard WordPress behavior.

<?php
// Example function to insert TOC before the second H2
function my_custom_toc_insert( $content ) {
    
    // Only run on single posts and if the post has at least two H2s
    if ( is_singular('post') && substr_count( $content, '
 1 ) {
        
        // Find the position of the second H2 tag
        $first_h2 = strpos( $content, '<h2' );
        $second_h2_position = strpos( $content, '

This code will automatically process the [ez-toc] shortcode in the correct context when the main content is displayed with the_content().

Troubleshooting Common Issues

• TOC Not Styled: If your manually placed TOC lacks styling, ensure you are using the ez_toc_display() function and not do_shortcode(). Also, verify that the "Theme" selection in the plugin's settings is not set to "None."
• Shortcode Options: The available attributes for the [ez-toc] shortcode (e.g., label="", heading_levels="") are documented by the Easy Table of Contents team. Using ez_toc_display() respects the global settings configured in the plugin's options page.

By following these methods, you can gain precise control over where your Table of Contents appears while avoiding the common pitfalls of using the shortcode outside of its intended context.