Table of Contents Block in WordPress: 4 Great Ways | CSS-Tricks

Serving a table of contents block in WordPress for blog posts (or any other type of long-term written content) is a good idea for two reasons:

  • It helps users jump in the post to get what they need (and hopefully not get in their way).
  • Provides SEO value.

The RankMath SEO plugin counts as part of your page’s score (which indicates you should have one), because of that second score. Find out what Google is likely to offer you if you do it right:

Screenshot of a typical Google search results element with a breadcrumb above the page title, then the page description.  A purple box is drawn around four links below the page description to show how adding a table of contents block in WordPress can add those links in search results for additional user convenience,

It makes sense that other WordPress SEO plugins like Yoast would offer a table of contents as a baked-in extra for the plugin. If you are committed to using Yoast, I think it is a good idea to use just that. But I admit that it’s not my favorite to feel locked out to a plugin because it offers a subtle feature that you then depend on.

So what are the options?

Table of contents

What to Look for in a WordPress Table of Contents Template

Here are some things to look for and think about when choosing a TOC block:

  • customizable head – Several options put the ‘Table of Contents’ header on top of the actual table of contents, which makes sense. Can you turn it off or customize it? What is the level of the head? Having the ability to disable the heading may be necessary for layout, and choosing heading levels can help ensure proper HTML semantics.
  • Collapse – In the framework of making the TOC less annoying, many offer a feature to switch the TOC block between the open and closed state. do you want that? Are you OK with the fact that it will likely require some javascript to work? Are you switching access to it? Could it be the default state you want?
  • Choose titles to include – Maybe you just want all <h2> Elements to form a table of contents. Can you do that? Do subheadings create a “nested” list? do you want that? Can you turn off certain levels of headers? Can you tell the block just include it <h2> via <h4>? Are there things other than the headers you want to be part of the TOC?
  • Editable links Many WordPress table of contents plugins usually grab literally all the titles. Perhaps you want to shorten, lengthen or change a specific link in the table of contents; As in, it doesn’t have to be the exact text of the header it’s linked to. Can you do that?
  • Include additional links – Maybe you want to link to something that isn’t a title for the content. It might have been added to the theme using a custom field in WordPress, or it’s part of the general theme like the comments section. Can you add (or remove) those as addresses in the block?
  • Block editor support – That’s kind of the point of this blog. I haven’t included many non-blocking options. But there sure are old school versions of this [shortcode]or that you implement in another way. I’m mostly concerned about blocks, although I could easily see a situation where your goal would be to put the table of contents elsewhere in a template (sidebar, perhaps?). Therefore, having multiple options and modularity may be helpful.
  • Design Options – Personally, I like to carry my own design (surprise!) and even remove any stylesheets (or scripts) the plugin tries to bring in during the flight. But I can imagine more people want their table of contents to look good and be able to control it from an aesthetic point of view directly from the editor. This means that it would be nice to have blocking options for colors, fonts, spacing, etc.
  • Semantic coding – It might be helpful to have a peek at the HTML generated by the ‘Table of Contents’ block of your choice to make it make sense. I’ve seen plugins create HTML lists that don’t actually nest lists, for example, but instead add classes to list items to create a look Overlapping. no thanks. I’m not sure there is an official HTML format that is best for SEO, so semantic coding is the best you can do.
  • Address identifiers – For a linked table of contents to work, all headers must have identifiers, so there’s something to be linked. I think any plugin here worth their salt would add them to the titles Just in case they don’t already have one, but you might want to check it out; Otherwise, you risk disrupting existing links or possibly even design and functionality. Also think about the identifiers that are generated. For example, I use the Add Anchor Links plugin, which adds a link icon (🔗) next to all addresses to make the identifiers accessible. The identifiers it generated were identical to the identifiers generated in the table of contents, which caused a duplicate identifier issue. Fixable, but just be aware of things like that.

Option 1: Use a custom table of contents plugin

Table of Contents plugin is a plugin that focuses only on the table of contents. nothing else. Here are some powerful options where this is the case.

heroic table of contents

The ability to edit/add/remove headers from the table of contents – even after creating it automatically – is very powerful and unique to this plugin. It allows you to open and close it (optionally) as well, which is great as a target for those, as they should make links useful rather than content getting in the way. But beware, this puts you in the area of ​​inserting additional text and patterns that may or may not be perfect or something you feel comfortable doing.

Screenshot of the heroic table of contents lock in WordPress
(Recommended by Deborah Edwards Onoro)

Easy Table of Contents

This is Not Block block editor! Instead, it just inserts itself automatically, either by content type or through the meta box opt-in checkbox.

I find it a bit awkward that you can’t control where the table of contents goes with this plugin. It appears to be listing itself near the top of the posts, most likely after where a file is <!-- more --> Located.

Screenshot of WordPress Easy Table of Contents Lock


This is my favourite.

I like this because it doesn’t add any scripts or styles by default. It just makes the semantic HTML list of headers, links them, and that’s it. That’s how I like to roll.

Screenshot of SimpleTOC Table of Contents Lock in WordPress

LuckyWP Table of Contents

Lots of features, but I find it a bit embarrassing how it doesn’t have regular blocking controls. Instead, you get a completely customized UI for changing settings – and you can’t preview what it looks like in the block itself.

Screenshot of the LuckyWP Table of Contents Block in WordPress


This table of contents plugin seems to embrace the spirit of the WordPress theme editor quite well, but I find the settings a bit awkward. The options it offers don’t seem terribly useful (eg square bullets for the list? “15” space left?).

Screenshot of the GutenTOC Table of Contents plugin for WordPress.

Option 2: Wait for the Table of Contents feature to be stored in Core WordPress

As I type, there is an open pull request to enable the TOC block in the Gutenberg plugin. Presumably, if all goes well, she eventually makes her way to the core. That would be great if you asked me, but it doesn’t help solve the problem of needing a TOC block at this moment.

If that feature drops, I’d be highly inclined to use it. I hope I can do a search or query to find the TOC blocks that are in all posts, switch them to use the original block, and remove any plugin I have.

Option 3: Use the Table of Contents block which is a child feature of a WordPress plugin

I recommend not using a plugin that does a large number of things just because you want to use a small part of it. But hey, if it turns out that you can use a lot Of the things from a great plugin, it can be a bonus as far as managing fewer plugins overall.

Yoast Seo Premium

The free version of the Yoast SEO plugin does not have it, but for just $99 a year, the Yoast SEO Premium plugin does. It has almost no features at all. Just add it as a block, then it pops up. You can edit or remove the address – it’s almost like a “sub-block”.

The list of links is not editable, but it does update in real time when you change the titles in the content, something that most of the other links I’ve tested haven’t. Super basic, no design or features, but I kind of like it. I wouldn’t run Yoast for this feature, especially for a paid premium, but if you’ve been using Yoast anyway (for a long time) you can also go this route.

Screenshot of the Yoast SEO plugin's table of contents block in WordPress.

Ultimate Plugins for Gutenberg

This is perhaps the most elegant part of the TOC that I have come across. Again, I’m tired of using an all-in-one plugin for one specific feature, but the other features in this plugin are things you can use then it’s a solid choice.

Screenshot of the Ultimate Addons plugin for the Gutenberg Tablew of Contents plugin in WordPress.

Option 4: DIY Your DIY Table of Contents Template

Making blocks yourself is out of the question! I’ve done this many times with create-guten-block , although I may have come across @wordpress/create-block these days. This puts you in the land of JavaScript, so you’ll parse the post’s content with JavaScript, find the headings in the post’s content, and build things from there. I would say kind of middle to advanced lands. On the one hand, it’s an extra technical debt, and on the other hand, you at least have complete control because it’s your own token.

Since we focus on building blocks, Advanced Custom Fields has a very powerful method for building custom blocks that brings that power back to PHP-land. This way, if you are only interested in building a table of contents from other address blocks, the code becomes a lot easier.

Bill Ericsson has a post – “Accessing Block Data with PHP parse_blocks() And render_block() – This eventually creates a literal “Table of Contents” block. This concept he gives is a very useful reference for how to iterate blocks in a post and produce an HTML menu.


If I use Yoast SEO Premium on a site, I will just use it. If not, I’ll go for SimpleTOC. That’s what we did here in CSS-Tricks. Once the core feature (🤞) drops, I’ll do a rainy day project to move all posts that are currently using the table of contents plugin to using the WordPress core block (assuming it was fine).

Leave a Comment