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

Learning how to add a table of contents to WordPress posts is one of the most impactful improvements you can make to your content strategy. A well-structured table of contents improves user experience, helps readers navigate long articles, and can earn you coveted jump-link sitelinks in Google search results. In this guide, you will find every method available — from beginner-friendly plugins to manual HTML and PHP approaches — so you can choose the one that best fits your workflow.

Why You Should Add a Table of Contents to WordPress Posts

Before diving into the how-to steps, it is worth understanding the concrete benefits of adding a table of contents (TOC) to your WordPress content.

Improved User Experience and Readability

Long-form content exceeding 1,500 words can feel overwhelming without clear signposting. A TOC gives readers an at-a-glance overview of everything covered, allowing them to jump directly to the section most relevant to their needs. This reduces friction and keeps visitors on your page longer.

SEO Benefits and Rich Snippets

Google frequently displays jump links beneath search results when it detects a well-structured table of contents on a page. These sitelinks increase your result's visual footprint in the SERP, which can significantly improve your click-through rate. Additionally, anchor-linked headings help search engine crawlers understand your content hierarchy and topical depth.

Reduced Bounce Rate

When visitors can immediately find what they are looking for, they are far less likely to leave immediately. A TOC acts as an internal navigation system, encouraging deeper engagement with your content.

Method 1: Using a WordPress TOC Plugin (Recommended for Beginners)

The fastest and most reliable way to add a table of contents is with a dedicated plugin. Several excellent free options exist in the WordPress repository.

Option A: Easy Table of Contents Plugin

Easy Table of Contents is one of the most popular choices, with over 300,000 active installations. It automatically generates a TOC from your heading tags with minimal configuration.

1. Log in to your WordPress dashboard and navigate to Plugins > Add New.
2. Search for Easy Table of Contents in the search bar.
3. Click Install Now next to the plugin by Magazine3, then click Activate.
4. Go to Settings > Table of Contents to open the plugin options panel.
5. Under Enable Support, check the box next to Post (and Page if desired).
6. Set the Auto Insert option to automatically place the TOC before the first heading or after the first paragraph — whichever suits your layout.
7. Choose which heading levels (H2, H3, H4) to include in the TOC.
8. Select a counter style (numeric, alphabetic, or none) and a TOC title such as "Table of Contents".
9. Click Save Changes and open any existing post to confirm the TOC appears correctly.

Option B: LuckyWP Table of Contents

LuckyWP integrates natively with the Gutenberg block editor, making it an excellent choice if you prefer a block-based workflow.

1. Install and activate LuckyWP Table of Contents from Plugins > Add New.
2. Open any post in the Gutenberg editor.
3. Click the + block inserter and search for Table of Contents.
4. Insert the block at the position where you want the TOC to appear.
5. Use the block settings panel on the right to configure heading levels, styling, and whether to make the TOC collapsible.
6. Publish or update the post to save your changes.

Method 2: Adding a Table of Contents with the Gutenberg Block Editor (No Plugin)

If you prefer to avoid additional plugins, WordPress 6.1 and later includes a native Table of Contents block in the core block library. This approach keeps your plugin count low and leverages native performance.

Using the Core Table of Contents Block

1. Open the post you want to edit in the Gutenberg block editor.
2. Click the + block inserter at the position where you want the TOC — typically just below your introduction paragraph.
3. Search for Table of Contents and select the block provided by WordPress core.
4. WordPress will automatically detect all heading blocks in the post and generate anchor links.
5. In the block settings sidebar, choose which heading levels to include and whether to display the TOC as a numbered or bulleted list.
6. To ensure anchor links work correctly, click on each Heading block and verify that the HTML Anchor field in the Advanced settings panel is populated. WordPress generates these automatically, but you can customise them.
7. Update and preview your post to confirm all links scroll correctly to the relevant sections.

Customising the TOC Appearance with Theme Styles

The native block inherits your theme's typography and colour palette. You can override these via your theme's theme.json file or through Appearance > Editor > Styles if you are using a Full Site Editing theme.

Method 3: Manually Adding a Table of Contents with HTML

For developers or advanced users who want full control, manually coding a TOC gives you maximum flexibility. This method involves adding anchor IDs to your headings and creating a linked list at the top of the post.

Step-by-Step Manual HTML TOC

1. Open the post in the Gutenberg editor and switch to Code Editor mode via the three-dot menu in the top-right toolbar (or press Ctrl+Shift+Alt+M).
2. Add an id attribute to each heading you want to link to. For example:

<h2 id="why-use-a-toc">Why Use a Table of Contents?</h2>
<h2 id="plugin-method">Using a Plugin</h2>
<h2 id="manual-method">Manual HTML Method</h2>

1. At the top of the post content, before your first paragraph, add an unordered or ordered list with anchor links pointing to those IDs:

<nav class="toc">
  <p><strong>Table of Contents</strong></p>
  <ol>
    <li><a href="#why-use-a-toc">Why Use a Table of Contents?</a></li>
    <li><a href="#plugin-method">Using a Plugin</a></li>
    <li><a href="#manual-method">Manual HTML Method</a></li>
  </ol>
</nav>

1. Switch back to the Visual editor and confirm the layout looks correct.
2. Publish or update the post and test each link in the preview to make sure smooth scrolling works.

Adding Smooth Scroll Behaviour

By default, clicking an anchor link jumps instantly to the target section. You can enable smooth scrolling by adding the following CSS to your theme's Additional CSS panel under Appearance > Customize:

html {
  scroll-behavior: smooth;
}

Method 4: Adding a TOC Programmatically with PHP

If you manage multiple sites or want to automate TOC insertion across all posts without a plugin, a PHP snippet is the most scalable solution. You can add this to your child theme's functions.php file.

Automatically Injecting a TOC via the_content Filter

The following snippet parses heading tags from post content and prepends a generated TOC automatically. Add it to your functions.php or a site-specific plugin:

function wpai_auto_table_of_contents( $content ) {
    if ( ! is_single() || ! in_the_loop() || ! is_main_query() ) {
        return $content;
    }

    preg_match_all( '/<h([2-3])[^>]*id=["\']([^"\']+)["\'][^>]*>(.*?)<\/h[2-3]>/i', $content, $matches );

    if ( empty( $matches[0] ) || count( $matches[0] ) < 3 ) {
        return $content;
    }

    $toc = '<nav class="auto-toc"><p><strong>Table of Contents</strong></p><ol>';
    foreach ( $matches[2] as $index => $anchor ) {
        $title = wp_strip_all_tags( $matches[3][ $index ] );
        $toc  .= '<li><a href="#' . esc_attr( $anchor ) . '">' . esc_html( $title ) . '</a></li>';
    }
    $toc .= '</ol></nav>';

    return $toc . $content;
}
add_filter( 'the_content', 'wpai_auto_table_of_contents' );

Running a WP-CLI Command to Flush Cache After Changes

After updating functions.php, if you use a caching plugin, flush the cache so your changes appear immediately. You can do this via WP-CLI:

wp cache flush

If you use WP Super Cache or W3 Total Cache, the equivalent commands are:

wp super-cache flush
wp w3-total-cache flush all

Best Practices for Table of Contents in WordPress

Regardless of which method you choose, following these best practices will ensure your TOC adds real value rather than cluttering your posts.

Only Add a TOC to Long-Form Content

A table of contents makes sense for posts with at least four or five distinct sections. Adding one to a 400-word post can look out of place and may actually hurt readability. Most plugins let you set a minimum heading count threshold before the TOC auto-inserts, which is a sensible default to configure.

Use Descriptive Heading Text

Because TOC entries are pulled directly from your heading text, make sure every H2 and H3 clearly describes the section it introduces. Vague headings like "More Info" become equally vague TOC links, which defeats the purpose.

Keep the TOC Above the Fold

Place your TOC immediately after the opening introduction paragraph so it appears without scrolling on most screens. This ensures readers see the navigation option before they decide whether to continue reading.

Test Anchor Links After Updating Content

If you edit heading text after publishing, automatically generated anchor IDs may change, breaking existing TOC links. Always preview and test anchor navigation after making significant edits to post headings.

Consider a Collapsible TOC on Mobile

On mobile devices, a long TOC can push your actual content far below the fold. Most TOC plugins offer a collapsible toggle option. Enable it to improve the mobile reading experience without sacrificing navigation functionality.

Frequently Asked Questions

Does adding a table of contents to WordPress posts help with SEO?

Yes. A table of contents with anchor links helps search engines understand your content structure and can trigger jump-link sitelinks in Google search results, increasing your click-through rate. It also encourages longer page sessions, which is a positive engagement signal.

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 do not load external resources and generate minimal JavaScript. If performance is a priority, the native Gutenberg TOC block or the manual HTML method have zero plugin overhead.

How do I add a table of contents to all WordPress posts automatically?

Use a plugin with the Auto Insert option enabled (such as Easy Table of Contents), or add the PHP the_content filter snippet shown in Method 4 of this guide to your child theme's functions.php file. Both approaches will apply the TOC to all qualifying posts without manual intervention.

Can I style the table of contents to match my theme?

Absolutely. Most TOC plugins include basic styling options in their settings panels. For advanced customisation, add CSS rules targeting the plugin's wrapper class (e.g. .ez-toc-container or .auto-toc) in Appearance > Customize > Additional CSS or your theme's stylesheet.

Adding a table of contents to your WordPress posts is a straightforward improvement that pays dividends in user experience and search visibility. Whether you opt for a plugin, the native Gutenberg block, hand-coded HTML, or a PHP filter, each approach outlined in this guide will get you to the same goal. If you want to streamline tasks like this even further, WP AI Agent is a powerful tool that lets you manage WordPress tasks — including configuring plugins, editing theme files, and optimising content — through simple natural-language AI chat, saving you significant time and technical effort.