How to Add a Table of Contents to WordPress Posts

Adding a table of contents to WordPress posts is one of the most effective ways to improve your site's user experience, help readers navigate long-form content, and earn coveted jump-link features in Google search results. In this comprehensive guide, you will learn every practical method available — from beginner-friendly plugins to manual PHP and block-based approaches — so you can choose the solution that best fits your workflow.

Why You Should Add a Table of Contents to Your WordPress Posts

Before diving into the how-to steps, it is worth understanding why a table of contents matters. Search engines like Google frequently pull table-of-contents links into the search snippet, giving your page additional blue links that increase click-through rates. From a reader's perspective, a clear contents list sets expectations, reduces bounce rates, and keeps visitors engaged longer — all positive signals for SEO.

Improved navigation: Readers can jump directly to the section they need.
Better SEO: Google may display sitelinks from your TOC in search results.
Accessibility: Screen readers and keyboard users benefit from clear anchor links.
Professionalism: Long posts look polished and authoritative with a TOC.
Lower bounce rate: Users find value faster, encouraging them to stay.

Method 1 — Using a WordPress Plugin (Easiest Approach)

The quickest way to add a table of contents to WordPress posts is through a dedicated plugin. Several reliable, well-maintained options are available in the official WordPress plugin repository.

Step-by-Step: Installing Easy Table of Contents

Log in to your WordPress dashboard and navigate to Plugins > Add New.
Search for Easy Table of Contents in the search bar.
Click Install Now next to the plugin by Magazine3, then click Activate.
Go to Settings > Table of Contents to open the plugin configuration panel.
Under Enable Support, check the Post checkbox (and Page if desired).
Set Auto Insert to your preferred position — options include Before first heading, After first paragraph, or Top of content.
Choose which heading levels (H2, H3, H4) should appear in the TOC.
Select a visual theme or leave it at the default, then click Save Changes.
Open any existing post or create a new one — the TOC will now appear automatically whenever your post contains the minimum number of headings (default: 4).

You can also override the automatic placement by adding the shortcode [ez-toc] anywhere inside the post editor to manually position the table of contents exactly where you want it.

Controlling the TOC Per Post

Easy Table of Contents adds a meta box to the post editor called Table of Contents. From there you can toggle the TOC on or off for individual posts, change the title, and exclude specific headings — giving you granular control without touching any code.

Method 2 — Using the Gutenberg Block Editor

If you prefer a code-free, plugin-light approach and are already using the WordPress block editor, several block-based solutions make adding a table of contents straightforward.

Using the Rank Math TOC Block

Install and activate the Rank Math SEO plugin from the plugin repository.
Open your post in the Gutenberg editor.
Click the + (Add Block) button and search for Table of Contents.
Select the Rank Math — Table of Contents block.
Place the block wherever you want the TOC to appear in your content.
In the block settings sidebar, choose which heading levels to include and toggle options like list style (bulleted or numbered) and collapsibility.
Click Update or Publish to save.

Using the GenerateBlocks or Kadence Blocks TOC Block

Premium block libraries such as Kadence Blocks and GeneratePress/GenerateBlocks also ship with dedicated Table of Contents blocks. The workflow is identical — add the block, configure heading levels in the sidebar, and save. These options are ideal if you are already using one of these block suites to build your site.

Method 3 — Adding a Table of Contents Manually with PHP

For developers who want full control without relying on a plugin, you can programmatically generate a table of contents by parsing post content with PHP and injecting anchor IDs into headings. This approach requires adding code to your theme's functions.php file or a custom plugin.

How the PHP Approach Works

The script uses a regular expression to find all heading tags (h2, h3, etc.) in the post content, assigns each one a unique id attribute, and then prepends a generated list of anchor links before the content.

Example PHP Snippet

/**
 * Auto-generate a Table of Contents for single posts.
 * Add this to your theme's functions.php or a custom plugin.
 */
function mytheme_auto_table_of_contents( $content ) {
    if ( ! is_single() || ! in_the_loop() || ! is_main_query() ) {
        return $content;
    }

    // Find all H2 and H3 headings
    preg_match_all( '/<h([23])[^>]*>(.*?)<\/h[23]>/i', $content, $matches, PREG_SET_ORDER );

    if ( count( $matches ) < 3 ) {
        return $content; // Skip TOC if fewer than 3 headings
    }

    $toc  = '<nav class="toc"><p><strong>Table of Contents</strong></p><ol>';
    $new_content = $content;

    foreach ( $matches as $index => $match ) {
        $heading_text = wp_strip_all_tags( $match[2] );
        $anchor_id    = sanitize_title( $heading_text );
        $level        = $match[1];

        // Add anchor ID to heading in content
        $old_heading  = $match[0];
        $new_heading  = str_replace( '<h' . $level, '<h' . $level . ' id="' . esc_attr( $anchor_id ) . '"', $old_heading );
        $new_content  = str_replace( $old_heading, $new_heading, $new_content );

        // Add list item to TOC
        $toc .= '<li><a href="#' . esc_attr( $anchor_id ) . '">' . esc_html( $heading_text ) . '</a></li>';
    }

    $toc .= '</ol></nav>';

    return $toc . $new_content;
}
add_filter( 'the_content', 'mytheme_auto_table_of_contents' );

Paste this snippet into your active theme's functions.php file (or better yet, into a site-specific plugin). The function hooks into the_content filter, so it runs automatically on every single post without modifying your database content.

Adding Basic CSS for Your TOC

The snippet above adds a nav element with the class toc. You can style it by adding CSS to your theme's stylesheet or via Appearance > Customize > Additional CSS:

.toc {
    background: #f9f9f9;
    border: 1px solid #e0e0e0;
    border-radius: 4px;
    padding: 1rem 1.5rem;
    margin-bottom: 1.5rem;
    display: inline-block;
    min-width: 260px;
}
.toc ol {
    margin: 0.5rem 0 0 1rem;
    padding: 0;
}
.toc li {
    margin-bottom: 0.25rem;
}
.toc a {
    text-decoration: none;
    color: #0073aa;
}
.toc a:hover {
    text-decoration: underline;
}

Method 4 — Using WP-CLI to Audit Heading Structure Before Adding a TOC

Before rolling out a table of contents across a large WordPress site, it is smart to audit your posts to ensure they have proper heading structures. WP-CLI makes this easy from the command line.

Checking Posts with WP-CLI

Run the following WP-CLI command to list all published posts along with their IDs and titles so you can identify which posts are long enough to benefit from a TOC:

wp post list --post_type=post --post_status=publish --fields=ID,post_title,post_date --format=table

You can pipe this output to a CSV for review:

wp post list --post_type=post --post_status=publish --fields=ID,post_title --format=csv > posts-audit.csv

Once you have identified which posts need a TOC, you can use the Easy Table of Contents plugin's per-post controls or the PHP filter above to enable or disable the TOC selectively.

Best Practices for WordPress Table of Contents

Whichever method you choose, following these best practices will ensure your table of contents is effective and SEO-friendly.

Use a Consistent Heading Hierarchy

Your TOC is only as good as your heading structure. Always use H2 for main sections and H3 for subsections within an H2. Never skip levels (e.g., jumping from H2 to H4) because this confuses both readers and search engines. A well-organised heading hierarchy makes your TOC meaningful and scannable.

Set the Right Threshold

Do not show a table of contents on every post. Short posts with only two or three headings do not need one — they can actually make a short article look padded. Most plugins let you set a minimum heading count (typically 3–4) before the TOC appears. If you use the PHP method, notice the count( $matches ) < 3 check in the example above.

Keep TOC Titles Descriptive

Headings that appear in your TOC should be descriptive enough to stand alone. A link that reads "Introduction" or "Step 1" tells a reader nothing. Instead, write headings like "How to Install the Plugin" or "Configuring Advanced Settings" — these are far more useful both in the TOC and for SEO.

Consider Sticky or Collapsible TOCs for Long Content

For very long posts (3,000+ words), consider a collapsible TOC (supported by Easy Table of Contents and LuckyWP out of the box) or a sticky sidebar TOC that follows the reader as they scroll. These UI patterns dramatically improve usability on long guides and tutorials.

Test on Mobile

Many readers access content on mobile devices. Always preview your TOC on a smartphone after adding it. Ensure links are large enough to tap, the box does not overflow the viewport, and the overall layout does not push your main content too far down the page on small screens.

Frequently Asked Questions

Does adding a table of contents improve WordPress SEO?

Yes. A table of contents can improve SEO by helping Google understand your content structure and potentially generating jump-link sitelinks in search results. These sitelinks increase your listing's visual footprint and can significantly boost click-through rates from the search engine results page.

Will a TOC plugin slow down my WordPress site?

Lightweight TOC plugins like Easy Table of Contents and LuckyWP have a negligible performance impact. They add minimal JavaScript (for smooth scrolling) and very little CSS. Always test your page speed with a tool like Google PageSpeed Insights or GTmetrix before and after installing any plugin to confirm there is no significant impact.

Can I use a table of contents on WordPress pages as well as posts?

Absolutely. Most TOC plugins support both posts and pages. In Easy Table of Contents, simply check the Page option under Enable Support in the settings panel. The PHP method works on any content type by adjusting the conditional check — for example, replacing is_single() with is_singular() to cover both posts and pages.

How do I exclude specific headings from the table of contents?

With plugins like Easy Table of Contents, you can exclude headings by entering their exact text in the Exclude Headings field in the plugin settings or the per-post meta box. With the PHP approach, you can add a conditional inside the foreach loop to skip headings that match certain strings using strpos() or by checking against an exclusion array before adding them to the TOC list.

Adding a table of contents to your WordPress posts is a small investment that pays dividends in user experience, on-page time, and search visibility. Whether you go with a one-click plugin, a Gutenberg block, or a custom PHP solution, the steps outlined in this guide will have your posts navigable and polished in minutes. If you prefer to skip the manual setup entirely, WP AI Agent is an AI-powered tool that lets you handle tasks like installing plugins, configuring settings, and updating your WordPress site through simple natural-language chat commands — making site management faster and more accessible than ever.

How to Add a Table of Contents to WordPress Posts (Complete Guide)