Stabilize the Table of Contents Block

[priethor]

What problem does this address?

The table of content blocks was first released in Gutenberg 13.3 as an experimental block. A few releases later, no major bugs have been reported and we should start considering taking the block out of experimental.

What is your proposed solution?

Taking the block out of experimental would bring the block closer to shipping in WordPress 6.1.

Apart from removing the experimental flag in block.json it would be good to stabilize the dependent selector __experimentalGetGlobalBlocksByName, first introduced in #39610.

• @getdave do you see any reason not to stabilize the mentioned selector?
• @ZebulanStanphill @gziolo do you see any blocker not to stabilize the ToC block or other steps that should be done?

Pending items

• Stabilize the dependent selector __experimentalGetGlobalBlocksByName
• Table of Contents: support usage outside of Post Content #41173
• Table of Contents: fix undo history quirk #41031
• Add an aria-label attribute to the wrapping nav element
• Table of contents block – links don't work on initial page save #43595
• Add an option to control the heading levels
• Use the same block toolbar controls as the List block

[ZebulanStanphill]

My main concern with stabilizing the Table of Contents block is that, if the ideas in #41173 are implemented, it could drastically alter both the attribute schema and saved markup of the block. We might end up creating another backwards compatibility nightmare if we stabilize the block in its current form. I haven't had time to work on prototyping this idea, unfortunately.

The more I think about it, the more I realize that using a Table of Contents outside of the post content is actually the primary use-case for some website designs, so it feels almost wrong to have it be stabilized while it remains unusable there.

There's also the undo history bug described in #41031, which is just rather annoying to deal with. I have no clue how to fix it.

[bph]

While you are looking at another iteration on the Table of Content Block,
I am pulling the issue of missing options to modify how the headlines are displayed from the many comments from the original PR .
While testing in PR stage, I felt strongly that there needs to be a way for a user to change the style of the list created. Not everyone appreciates an ordered list, and would rather use bullet points or arrows or something else entirely.

During the various iterations it started out as bullet list.
After initial discussions about missing options, it was actually changed to an ordered list. Although, there were other voices to advocate for more options for the display of the headlines, it did not receive any further consideration,

• @paaljoachim commented on it.
• @juanmaguitar commented on it as well.

During the discussion, it was not accepted as a needed feature, and argued that it was in the theme developer's domain.

I still feel that an end user should be able to change the nature of the Table of Content list, via an option in the Sidebar, rather having the need to connect with a developer to modify the theme css.
In one comment it was mentioned that such settings should be in the Global Styles and deferred to a future interation.

To be consistent, most core blocks have myriad of options applied to each instance of the block, in addition to the theme.json settings for Global Styles.

For now, the current Table of Contents block doesn't provide neither block based options nor a theme.json or Global Style implementation to change the display of the Headlines.

With more options it would shine so much brighter, especially if it makes it into the next major WordPress release.

[ndiego]

I 100% agree with @bph and @ZebulanStanphill assessments. This block, while a great start, could use some additional love. To echo some of the previous comments:

1. The largest area of concern to me is the fact that it does not work outside of post content, thereby making the block unusable in the Site Editor. Without a fix here, I anticipate a lot of user confusion and frustration. You are able to add the TOC block to templates, yet it doesn't display anything.
2. The block needs more style settings to be consistent with other Core blocks. Color, typography, list style, and dimensions would be a good start.
3. There needs to be a way to control the headings that are displayed. A common use case is only to display H2 and H3s, but not the H4, H5, etc.

[getdave]

@getdave do you see any reason not to stabilize the mentioned selector?

As far as I'm aware there is no reason not to stablise this selector. Also noting it is not widely used.

[Mamaduka]

I think styling enhancements aren't necessary blockers for stabilization. These can be done after.

The "Table of Contents outside of the post content" is nice to have but not a blocker, in my opinion. My best guess is that we'll have to use dynamic rendering and parse content blocks to achieve this.

The "undo bug" breaks editor history, so it probably should be fixed before we consider stabilizing the block — recent findings from @kevin940726 on this issue - #41031 (comment).

P.S. It would be nice to stress test the block on large posts and see if it affects typing.

[ndiego]

Yeah, I am all for stabilizing. I just don't think we should include it in Core until the block is a bit more full-featured. While a great step forward, it feels incomplete.

[gziolo]

Yeah, I am all for stabilizing. I just don't think we should include it in Core until the block is a bit more full-featured. While a great step forward, it feels incomplete.

Technically speaking, the issue is about exposing this block for WordPress Core by removing the experimental flag that ensures Table of Contents block can be used only with the Gutenberg plugin.

The more I think about it, the more I realize that using a Table of Contents outside of the post content is actually the primary use-case for some website designs, so it feels almost wrong to have it be stabilized while it remains unusable there.

The "Table of Contents outside of the post content" is nice to have but not a blocker, in my opinion. My best guess is that we'll have to use dynamic rendering and parse content blocks to achieve this.

We need to make the decision whether this block should be general purpose and work everywhere or we limit its usage to the post editor. One way to approach it could by setting in block.json the ancestor field to core/post-content. It probably won't work out of the box, but it shouldn't be too difficult to implement.

In general, it's a challenge to ensure that the Table of Contents block stays in sync when some dynamic blocks change outside of the place where the table of contents gets updated. It's also an issue when using the post editor and you have a Reusable block with heading that can be modified in every place on the site.

[joedolson]

The table of contents block also needs to add an aria-label attribute to the wrapping nav element. There will almost always be other nav elements present on the page (the main navigation, at minimum), so this needs to be made clear. The obvious choice for single post views is just 'Table of Contents', but if it's used outside of a single post view, it'll need further differentiation from other tables of contents.

[apeatling]

cc @priethor to see if this is still important for 6.1.

[ZebulanStanphill]

I should note that due to being busy with several other things, it is unlikely that I will be able to help much with stabilizing the Table of Contents block, besides reviewing PRs from other people. If anyone wants to tackle the aforementioned issues, feel free to do so, because I simply don't have the time available to do so right now.

If you ask me, the switch back to dynamic rendering and the question of a bullet style option are two things that must be tackled prior to the block being considered stable.

[priethor]

I think it is still worth exploring having the ToC block in 6.1. I don't think being limited to the Post Editor is a blocker; to me, it's an opportunity to include it earlier with a limited scope and iterate later on it.

[ZebulanStanphill]

My primary concern is not the limitations it would have if merged now, but rather the backwards-compatibility burden it would cause later on, if (or most likely, when) the implementation changes. I've already seen several recent cases of core blocks having to make a bunch of compromises due to an inability to update existing static-rendered blocks on the front-end. For example:

• The reverted attempt to remove the wrapping <div> from the Button block's markup. Update the buttons block to use the new color support flag. #21266, Revert the button block to the previous markup #21923
• Adding a wp-block-heading class to the Heading block. [Heading block] Add a wp-block-heading CSS class #42122
• Difficulties in adding a new default layout mode for the Group block. Try "constrained" content width as new layout type #42763

[priethor]

Bringing this to @michalczaplinski and @ockham's attention as a decision needs to be made for 6.1.

While I'm all in for including this in core feature-wise, apart from that, it hasn't been released in Gutenberg in a stable manner yet and won't be before Beta 1.

[michalczaplinski]

Based on all the concerns in the current thread I would not feel comfortable including the Table of Contents block in the 6.1 in its current form.

It seems that we'd at least need to complete the following:

• Table of Contents: fix undo history quirk #41031 - this is just a bugfix but an annoying one it seems.
• Table of Contents: support usage outside of Post Content #41173 - adding support for this likely means switching to dynamic rendering of the block. This means that if we were to stabilize the current (static) version of the block, it would create compatibility problems when adding this fix later on.
• Add the ability to customize the style of the list in the Table of Contents as mentioned by @bph in this comment above.

The Feature Freeze for 6.1 is in exactly 2 weeks. Are there any volunteers that would like to work on those features so that we could stabilize the ToC block and include it in the 6.1 ? Are there any other issues that would be considered must-haves? 🙂

[ndiego]

The TOC block was not included in the 6.1 Beta, so I am going to remove this PR from the 6.1 Project Board.

[priethor]

Let's aim to have this for 6.2 🙏

[NicoHood]

So is this block still on the roadmap for 6.2? It would be great to have, as its been in development for so long now :)

[annezazu]

Pinging 6.2 Editor Tech co-leads @Mamaduka and @ntsekouras as a heads up as this was punted from 6.1. Going to add to 6.2's project board for now for consideration.

[ntsekouras]

I haven't worked or followed much of the work for this block, but after reading the described issues, I'd have to echo @michalczaplinski comment

Based on all the concerns in the current thread I would not feel comfortable including the Table of Contents block in the 6.1 in its current form.

Since the discussions for 6.1 there was no activity at all for moving this forward, so I don't think we can stabilize it.

What we should do though is try to actively move forward the remaining issues as soon as possible, in order to include it in 6.3.

[priethor]

Let's punt this issue from 6.2, as it's in the same situation as it was before 6.1.

[mahnunchik]

Any chance to have ToC block enabled in 6.2?

Question: how to enable ToC block manually? I really need it 😉

[annezazu]

It will not be included in 6.2! As you can see above, that decision was made in January. If you want to use it for now, you can use the Gutenberg plugin but please read this article first before considering using the plugin that's meant for very early adoption.

[mahnunchik]

@annezazu Thank you. How to understand which version of Gutenberg plugin is bundled with WP by default?

According to this table https://developer.wordpress.org/block-editor/contributors/versions-in-wordpress/ I can install Gutenberg plugin versions from 14.2 to 15.1 for 6.2

[joedolson]

@mahnunchik The version of the editor included in core isn't an exact match for any released version of Gutenberg. Generally speaking, there's a release defined as the final release that will be included in core, but later bug fixes will be merged back into core even while further feature development continues. So version 6.2 contains a version of the block editor that's very similar to Gutenberg version 15.1, but it is not identical.

[annezazu]

Looping back on this ahead of 6.3. To focus the discussion and provide an update, the following are likely needed for inclusion in 6.3:

• Table of Contents: support usage outside of Post Content
• Table of Contents: fix undo history quirk
• Add an option to control the headings that are displayed.
• Resolve this autosave issue: Table of contents block – links don't work on initial page save #43595

In the future, more styling options can be added. I'm going to add this to the broader Phase 2 board in case someone can pick the work up.

[bph]

Thank you for picking up this thread again, @annezazu

TBH, the architecture might need refactoring, so a styling of the list is possible, without losing the automatic update with new headlines. At the moment, the TOC block is restricted as a hard-coded ordered list. A conversion to a bulleted list is only possible by using the crutch of converting it to a static list, that then loses the ability to automatically update when the writer adds a headline or change the order of the headline.

To update the TOC with the updated outline of the post the user is forced either to wait to add the TOC block until the post is fully composed or employ the following ritual:

• delete the static list block,
• add the TOC block again that shows the new outline.
• Covert to static list again

The user will expect the Table of Content block to update automatically. A restriction to the numeric block is not a suitable trade-off.

I think styling enhancements aren't necessary blockers for stabilization. These can be done after. (@Mamaduka)

It is my understanding, - and I have been wrong before many, many times, - that for more styling options, there would need to be more flexibility in the underlying markup, that won't be backwards compatible, unless the block includes a conversion function, or is a dynamically rendered block. Either way would need to get some consideration before making it into Core.

[MatzeKitt]

At the moment, the TOC block is restricted as a hard-coded ordered list.

Why is this a bad thing? A TOC is, by design, an ordered list, since it’s an ordered structure of headlines in the post. For my understanding, everything else would be semantically incorrect for a TOC.

[bph]

Here is the Custom CSS to transform the numbers in an ordered list to bullets: TY @justintadlock

 ol {
  list-style: disc;
}

Open the Styles sidebar, scroll all the way down to "Blocks",scroll to 'Table of Content' block, click on 'Additional block CSS', copy/paste the snippet and don't forget to click the "Save" button. Now you can use the Table of Contents block with bullet points without having to convert to a static list.
(partial table of content in this post What’s new for developers? (April 2023))

I just leaving it here, in case there won't be any more styling tools for the Table of Contents block, as a reminder to create a block style for the bullet list and provide a work around for others

[richtabor]

The block needs more style settings to be consistent with other Core blocks. Color, typography, list style, and dimensions would be a good start.

Just following up that these are now added:

[richtabor]

The table of contents block also needs to add an aria-label attribute to the wrapping nav element.

The "Table of Contents outside of the post content" is nice to have but not a blocker, in my opinion. My best guess is that we'll have to use dynamic rendering and parse content blocks to achieve this.

@Mamaduka Is it possible to have it always pull headings from the post content, wherever the block is rendered on the page (within templates or not)? Re: #41173 (comment)

Seems these are the last two bits to get this in.

[richtabor]

At the moment, the TOC block is restricted as a hard-coded ordered list.

Perhaps we could use the same block toolbar controls as the List block, but apply list style CSS instead of changing the markup.

[ghost]

Are the authors Zebullan or Priethor still commited for this block to be stabilized? What course of action is proposed now? Plan A and plan B? There are some open issues. If all cannot be attained at the same time as it seems, what should be prioritized and what should be discarded? Let's discuss this to have a clear path.
Kindly,

(The Details block and the Footnotes block recently landed, and they had their scope limited in the development. So far so good despite the limitations. I just asked myself if that is also the way for the TOC block).

[annezazu]

There's a clear path right now. The blocker is someone diving in to do the work right now. For 6.3, we weren't able to get someone in place who could do so.

[ZebulanStanphill]

My schedule is very busy lately, so it is unlikely that I will be able to do much here, though I'll try and review any PRs relating to the block if I have the time.

[Mamaduka]

@annezazu, @priethor can you update the description and include list of items required for stabilization?

I’ll try to resolve those items before WP 6.4.

[priethor]

I've consolidated the remaining items in the issue description. 🚀

[Mamaduka]

The #54224 is ready for review. Fixes the undo quirk and page permalink bugs.

[bph]

As a follow-up on the decision that the Table of Content will not be shipping in 6.4, I removed it from the project board

[phanduynam]

Looks like the table of contents block is not published on wordpress 6.5.2