A while back I was working on a client site in the shopping recommendation niche. You know the type — long, detailed buying guides that walk readers through everything they need to know before making a purchase. The kind of post that hits 3,000 words before you even get to the actual recommendations.
The guides were well-written and genuinely useful, but there was a problem: readers had no easy way to jump to the section they actually cared about. Someone who just wants to know the best budget option shouldn’t have to scroll past an intro, a methodology section, and a full comparison table to get there.
The fix was obvious — add a table of contents. The tricky part was finding a block that did it the way I wanted.
Why I Ended Up Building My Own
There are TOC plugins out there, but most of them felt like overkill for what I needed — bloated settings panels, custom heading blocks, or JavaScript that fights with the editor. I wanted something that worked with the core Heading block, stayed out of the way, and just worked.
So I built Simple WP Table of Contents Block.
How It Works
The idea is straightforward: you insert the Table of Contents block wherever you want it to appear in the post — usually near the top — and it takes care of everything else.
The moment you add it, the block starts listening to your editor in real time. Every core Heading block in the post gets picked up automatically and added to the TOC preview. No configuration, no mapping, no rebuilding anything manually.
On the frontend, the block renders a nested navigation list that mirrors the heading hierarchy of your post. H2s become top-level items, H3s nest under them, and so on. Clicking a link smoothly scrolls the reader to that section.
The One Feature I’m Most Happy With
When you select the TOC block, the sidebar shows a checklist of every heading in the post. Each one has a toggle. Turn it off and that heading disappears from the table of contents — the reader won’t see it, and the anchor link won’t exist in the saved markup.
This was important for the client site. Some sections were more like internal signposts for the writer than navigational landmarks for the reader. Being able to exclude them without deleting or restructuring the post was exactly what was needed.
The checklist also reflects the heading hierarchy, so you can see at a glance how the post is structured while you’re editing it.
Under the Hood
The plugin extends the core Heading block with two custom attributes — one for the generated anchor slug, one for the exclude toggle. These get saved into the block markup when the post is published, which means the PHP renderer can parse the saved HTML directly to build the TOC on the frontend. No database queries, no shortcodes, no post meta.
Anchor IDs are generated automatically from the heading text and de-duplicated if two headings share the same text. The JavaScript and PHP use the same slugification logic, so what you see in the editor preview matches what gets rendered on the page.
Get It
The plugin is free and open source. You can grab it on GitHub:
github.com/IronLady/simple-wp-table-of-content
If you’re building long-form content in the block editor and want a simple, no-fuss way to add navigation, give it a try. And if something doesn’t work the way you’d expect, open an issue — I’m actively maintaining it.
Leave a Reply