What was once likely viewed as plugin territory is now a reality as part of the Gutenberg project. Yesterday, the team merged a pull request for a Table of Contents (TOC) block into the plugin’s codebase. It was a contribution driven by developer Zebulan Stanphill, starting nearly a year ago.
The TOC block may feel a bit niche. However, there is obviously a need for it. There are at least two standalone block plugins to handle the feature, and several block library plugins cover it. Last week, a reader asked about such a solution. Soon, the Gutenberg plugin and, eventually, WordPress will have him and others covered.
The block is not currently available in the plugin on WordPress.org. It has not officially shipped yet. To test it, users will either need to clone the Gutenberg GitHub repository or grab a ZIP file of the nightly beta. It should land in Gutenberg 10.1 in the coming weeks for those who want to wait.
Including these more-niche blocks is a good direction for the project — a Footnotes block is also a possibility. While it can feel like stepping on the toes of plugin developers, WordPress needs to branch out. There is plenty of room for third-party devs to build other blocks. The experience is degraded when users have to sift through multitudes of plugins to find something core to their writing process. There are limits on what blocks should ultimately be included in the platform. However, WordPress is publishing software. Advanced writing features, such as TOCs and footnotes, belong firmly in the default setup.
The Table of Contents Block
This block is a bit different than other blocks users are accustomed to. A TOC is a list of all the headings in a document. In the case of WordPress and webpages in general, a TOC links to those headings. This allows users to jump around the page. The block depends on other blocks in the content, a slightly new concept for the block editor.
When first adding the block to an empty page, it will display a helper message.
Users must begin adding Heading blocks in their post to make use of the TOC block. Once they are added, each Heading is shown as a list item. The block also properly nests list items for sub-headings — an H3 goes into a sub-list under an H2, for example.
This is the moment things become more complex. On the web, a TOC needs to link to those headings so that readers can jump to the section they want to view. Right now, this does not happen automatically. Perhaps it will do so in the future, but users must manually add HTML anchors to make the linking part work. Ideally, the initial helper message would link to the documentation page on how to do this for new users.
Adding HTML anchors is easy. However, it could be a ton of work for long posts with dozens of headings.
To add the anchor, users must click on each Heading and navigate to the block options panel. Under the Advanced tab, enter a unique ID. It is easiest to name this after the text itself. A Heading block with “A New World” gets an anchor of a-new-world. This also helps when others are deep linking into posts, creating prettier URLs, such as yoursite.com/blog/post-name/#a-new-world.
The TOC block does not have any design settings. If users need to change the colors or other design-related elements, it is best to wrap it inside another block, such as Group or Cover.
If adding a heading for the Group block or before the TOC block, it will be added to the list. It is best to use the Paragraph block as a faux heading and change the font size.
Overall, the block works well. Except for the manual insertion of anchors, it is a welcome addition. Perhaps a plugin author will come along and write the code to make it automatic.
