How to Add a Table of Contents in WordPress (3 Ways)

A table of contents is one of those small additions that quietly improves a long post for everyone: readers can see the shape of the article before committing to it, jump straight to the part they came for, and orient themselves halfway down a 2,500-word guide. WordPress makes this less obvious than it should be — there’s a native block, but it hasn’t been in stock core for most of its life, so most sites end up using a plugin or hand-rolled HTML. This guide covers three ways to add a table of contents in WordPress, when each one makes sense, and the practical details (heading hierarchy, anchor IDs, mobile behaviour) that decide whether your TOC is genuinely useful or just decoration.

Why a table of contents is worth adding

The honest case for a TOC is mostly about reading experience, with a possible search bonus on top.

• Navigation on long content. Anything past roughly 1,000 words benefits. A reader who lands from search usually wants one specific answer — a TOC gets them there in one click instead of three scrolls and a bounce.
• It sets expectations. Seeing “Method 1, Method 2, Method 3, Best practices, FAQ” up front tells someone the article actually covers their question. That alone can keep them on the page.
• Engagement signals. People who find what they need stay longer and are likelier to click something else. That’s a second-order effect, not a ranking lever you pull directly, but it’s real.
• Possible jump-to-section links in Google. Google can show links to specific sections of a page directly in the search result, and it generates those from anchor-linked headings on the page. This is worth being precise about: you cannot make it happen. Google decides algorithmically whether to show them, they appear for some queries and not others, and there’s no markup that guarantees them. Well-structured headings with stable anchor IDs make your page eligible; nothing more.

Treat jump links as a bonus, not the goal. Build the TOC because it helps readers — if Google surfaces section links too, that’s upside.

Method 1 — The built-in Table of Contents block

WordPress does have a native Table of Contents block, and it does the obvious sensible thing: it scans the Heading blocks in your post and builds a nested list of anchor links automatically, updating as you add or rename headings.

The catch is availability, and this is where a lot of tutorials are misleading. The block was introduced back in Gutenberg 13.3 as an experimental block, which means it has shipped only inside the Gutenberg feature plugin — experimental blocks are stripped out before Gutenberg code is merged into WordPress core. So for years, “use the built-in block” really meant “install the Gutenberg plugin first.” The block is on the list of blocks slated to graduate into core with WordPress 7.1, planned for August 2026, so this is changing — but check your own install before assuming it’s there.

To find out where you stand:

1. Edit any post and click the block inserter (the + button).
2. Search for table of contents.
3. If it appears, insert it after your intro paragraph and you’re done — it populates from your headings automatically.
4. If it doesn’t appear, your WordPress version doesn’t expose it yet. You can install the Gutenberg plugin to get the experimental version, but be aware that’s a bleeding-edge plugin that changes the editor significantly — it’s fine for a test site, and a big commitment for a production one.

When it is available, this is the lowest-maintenance option: no extra plugin, no manual anchors, and the output is plain semantic HTML.

Method 2 — A dedicated table of contents plugin

This is what most sites actually use, and for good reason. A TOC plugin auto-generates the list from your existing headings — you don’t touch your content at all — and adds the presentation controls the core block doesn’t have.

Typical features worth looking for:

• Heading-level control: include H2 and H3 but skip H4 and below, so a long article doesn’t produce a 40-item wall of links.
• Collapsible / expandable: critical on mobile, where a long TOC can push your actual content below two screens of links.
• Sticky sidebar TOC: the list follows the reader down the page, often highlighting the current section. Great on desktop, usually best disabled on mobile.
• Automatic insertion rules: “add a TOC to every post over N headings, before the first heading” — set once, applies site-wide, including to your archive of older posts.
• Per-post overrides: the ability to exclude a specific post, or exclude a specific heading from the list.
• Anchor ID generation: most plugins create IDs from heading text automatically. Check what they look like, because these become part of your URLs.

Many all-in-one SEO suites now bundle a TOC block too, so check what you already have installed before adding another plugin. The trade-off with any plugin is the usual one — another thing to keep updated, and a dependency your anchor links are quietly tied to. If you ever switch TOC plugins, verify the new one generates the same ID format, or every deep link anyone has shared to your sections breaks.

Method 3 — Manual HTML with anchor IDs

No plugin, total control, and worth understanding even if you use methods 1 or 2, because it’s what those tools generate under the hood. A table of contents is just an unordered list of links pointing at IDs on the page.

Step one: give each heading an ID. In the block editor, select a Heading block, open the block settings sidebar, expand Advanced, and type a value into the HTML anchor field — for example why-a-toc. WordPress renders that as:

<h2 id="why-a-toc">Why a table of contents is worth adding</h2>

Step two: link to it. Add a List block at the top of your post and link each item to the ID with a leading hash:

<ul><li><a href="#why-a-toc">Why a table of contents is worth adding</a></li><li><a href="#method-1-core-block">Method 1 — the built-in block</a></li></ul>

That’s the whole mechanism. Clicking the link jumps the browser to the element with the matching id, and the anchor also works as a shareable URL: https://example.com/post/#why-a-toc lands a visitor directly on that section.

Two practical notes. If your theme has a sticky header, jumped-to headings can end up hidden underneath it — the fix is a small amount of CSS (scroll-margin-top) on your headings. And keep IDs lowercase with hyphens, no spaces or accents, so they survive being copied into chat apps and emails intact.

Manual is the right choice for a handful of cornerstone pages where you want exact control over wording and which sections appear. It’s the wrong choice for a 300-post blog — you’ll never keep it in sync.

Best practices that actually matter

Build on a clean H2/H3 hierarchy

A table of contents is only as good as your headings. Use one H1 (your title), H2 for major sections, H3 for subsections beneath them, and don’t skip levels for visual reasons — jumping H2 to H4 because you liked the font size produces a confusing outline for both screen readers and your TOC. Write headings that make sense out of context, because in a TOC that’s exactly how they’re read.

This structure pays off beyond navigation. Clear, descriptive headings give you natural language to link between related posts, and internal links built on that vocabulary are more relevant than generic “click here” links — our guide to anchor text goes deeper on that. Full disclosure since it’s ours: if you’d rather not wire those links up by hand across an archive, our free plugin JnK Linkweave can auto-link chosen keywords to the posts you nominate. It’s one option among several, and manual linking works perfectly well on a small site.

Don’t include every heading

H2 and H3 is the sweet spot for most articles. Including H4s and H5s turns the TOC into a second article. If a section has one subsection, consider leaving the subsection out entirely — the goal is a scannable map, not a complete index.

Place it after the intro

Put the TOC below your opening paragraph, not above it. The intro is what convinces someone they’re in the right place; a block of links before any prose is disorienting, and on mobile it pushes your actual content below the fold.

Make it collapsible on mobile

On a phone, a ten-item TOC can occupy an entire screen. A collapsed-by-default toggle (“Contents ▾”) keeps it available without costing anyone their first impression of the article. Most TOC plugins offer this as a setting; if you’re doing it manually, HTML’s native <details> element gives you a toggle with no JavaScript.

Keep anchor IDs stable

This is the one that bites people. Once a section has an ID, treat it as permanent. If you rewrite a heading and your plugin regenerates the ID from the new text, every existing deep link to that section — from your own posts, from other sites, from someone’s bookmarks — now lands at the top of the page instead. When you must reword a heading, set an explicit manual anchor matching the old ID so the link keeps working. It’s the same discipline as not changing URLs casually, and it’s part of any decent on-page SEO checklist.

Which method should you pick?

Whichever route you take, the underlying HTML is identical: headings with IDs, and a list of links pointing at them. Get the heading structure right and every method works well.

Frequently asked questions

Does WordPress have a built-in table of contents block?

There is a native Table of Contents block, but it spent years as an experimental block available only in the Gutenberg feature plugin, because experimental blocks are removed before Gutenberg code merges into WordPress core. It is slated to graduate into core with WordPress 7.1, planned for August 2026. Search the block inserter for “table of contents” to check whether your install has it.

Will a table of contents get my page jump links in Google search results?

It might, but nothing guarantees it. Google can generate links to specific sections of a page in search results, and it builds those from anchor-linked headings on the page. Whether they appear is decided algorithmically per query, and there’s no markup that forces it. Clear headings with stable anchor IDs make your page eligible — treat section links as a bonus rather than the reason to add a TOC.

How do I link to a specific section of a WordPress post?

Give the heading an ID using the HTML anchor field under Advanced in the Heading block’s settings, for example why-a-toc. Then link to it with a leading hash, such as <a href="#why-a-toc">Jump to section</a>, or share the full URL with the anchor appended. Keep those IDs unchanged afterwards, because editing them breaks every existing link pointing at that section.