New Table Of Contents Block In WordPress Gutenberg

It looks like we’re finally getting a new Table of Contents (ToC) block in Gutenberg! It’s not out for release publicly yet, but I was able to test a nightly version of the plugin and it looks really good! Very easy to use, and it has the option of converting the ToC into a static list at any time. There were a couple of things I feel it can do better, but I’m liking what I see so far!

Getting Your Hands on the “Nightly” Gutenberg Build

The Gutenberg team periodically releases public builds of the plugin on GitHub, but to have access to the latest features before that, you have to install a bunch of software and know how to use the command line. Instead of doing this, the helpful chaps over at Gutenberg Times have taken it upon themselves to provide what they call “Nightly” Gutenberg builds, which compile the latest trunk version of Gutenberg and make it available as a download. You can even install the Git Updater plugin and update the Nightly builds directly from the WordPress dashboard like you would any other plugin. It’s very useful!

Using this, I download the latest version of Gutenberg containing the near-released Table of Contents block.

Inserting a ToC Block in Gutenberg

Once you’ve installed the nightly Gutenberg plugin, you can start editing any post or page to see it in action. You won’t notice immediately that you’re using something other than the default WordPress editor unless you know what you’re looking for.

As proof, here’s what happens when you type in “/” in a paragraph block to insert a Table of Contents block:

You can see we have a new block that wasn’t there before, thanks to the Nightly plugin. Just insert this block and start creating headings!

The ToC Populates in Real-Time with Headings

As you create headings in Gutenberg, you’ll see that the ToC block instantly updates itself by creating a list item for each heading, and indenting them if you create a sub-heading. Here’s a screenshot:

This is as easy as it gets. You don’t have to do anything extra, and the default settings work well. You can change the anchor text of any of the headings, and the block will update automatically. Everything works transparently.

For many people, this is exactly what they were looking for. Lots of previous attempts at a table of contents plugin use shortcodes, where you can’t see the impact in real-time.

Two Potential Problems with the ToC Block

At first glance, I notice two potential problems with the ToC block.

Unable to Control Indentation

The first problem is that you have no control over which headings appear or get indented. In my articles, I typically want just one level of indentation. So I only want H2 and H3 headings to appear in the ToC block. If I use an H4 heading for clarity, I often don’t want it showing up in the ToC because it looks cluttered.

I hope future iterations of the ToC block will allow us to control which headings appear.

TOC Includes Headings Above the Block

The ToC block will include ALL headings in the post or page, including those above the block itself. While this might make sense in some situations, I personally don’t think it’s appropriate. In my view, only headings below the block should be counted.

Both of these reasons – indentation control and headings above the block can be included later as enhancements. But even as it is right now, it’s a great addition. I’ve been using the Shortcode Table of Contents for years, even though it hasn’t been updated for a long time, because it just works, and lets me control my headings and indentations. But once these features are integrated into the default ToC block in Gutenberg, I’ll shift over to using it!