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: Rename __experimentalGetGlobalBlocksByName to getBlocksByName #58156
• Table of Contents: support usage outside of Post Content #41173: Table of Contents: Try dynamic rendering #72110
• Table of Contents: fix undo history quirk #41031: Table of Contents: Try dynamic rendering #72110
• Add an aria-label attribute to the wrapping nav element: Table of Contents: Add aria label to the nav element #71586
• Table of contents block – links don't work on initial page save #43595: Table of Contents: Try dynamic rendering #72110
• Use the same block toolbar controls as the List block (being able to switch between bullet styles): Table of Contents: Update toolbar controls #71587

User Stories

The following user stories reflect the desired behaviour from a user standpoint.

Writing and editing (content authors)

• As a content author, I should see the table of contents automatically update as I add, remove, or reorder headings, in order that I never have to build or maintain navigation by hand.
• As a content author, I should see an accurate preview of the table of contents while I'm still editing, in order that I can trust what I see before I publish.
• As a content author, I should be able to limit which heading levels appear - for example, only main sections, not sub-points - in order that the table of contents stays focused and useful on longer pages.
• As a content author, I should be able to choose between a numbered and a bulleted style, in order that the table of contents matches the look of the rest of my content.
• As a content author, I should see a clear message when my page has no headings yet, in order that I understand why the block looks empty rather than assuming it's broken.

Reading and navigating (site visitors)

• As a reader, I should be able to click any item in a table of contents and land exactly on that section, in order that I can move through long content quickly.
• As a reader, I should never click a table of contents link and end up on a missing or broken page, in order that I trust the site's navigation.
• As a reader, I should be taken to the right page of a multi-page article, even if the section I clicked is on a different page than the one I'm currently reading, in order that pagination doesn't break navigation.
• As a reader, I should see the table of contents laid out to match the structure of the page, with sub-sections nested under their section, in order that I can judge how the content is organised before I start reading.

Accessibility (readers using assistive technology)

• As a reader using a screen reader, I should be able to recognise the table of contents as a distinct, named region of the page, in order that I can jump straight to it or skip past it, rather than listening through it by accident.
• As a reader navigating by keyboard, I should be able to reach and move through the table of contents links in a predictable order, in order that I'm not stuck or disoriented.
• As a reader using a screen reader, I should be able to tell the table of contents apart from the site's main menu, in order that I don't confuse the two when there's more than one navigation region on the page.

Placing the block across a site (site builders)

• As a site builder, I should be able to add a table of contents once to a shared template, in order that it automatically appears on every post using that template, without adding it to each post individually.
• As a site builder, I should see a clear explanation in the editor when the table of contents can't show a live example while I'm editing a template directly, in order that I understand what it will actually do for visitors rather than assuming it's broken.
• As a site builder, I should be confident that a table of contents only ever lists headings from the specific post or page being viewed, never headings from the template itself or from any header, footer, or other reusable template part it includes, in order that every entry reliably takes a reader to part of the actual post.
• As a site builder, when I place the table of contents on a template that doesn't show one specific post - such as an archive, a search results page, or a "page not found" page - I should see an explanatory placeholder while editing, and it should quietly produce nothing on the actual page, in order that it never tries to show something meaningless to a reader.

Supporting content built with other blocks (authors and developers)

• As a content author, I should have my headings count towards the table of contents no matter which block I used to create them, in order that I'm not forced to change how I write just to get working navigation.
• As a theme or plugin developer, I should be able to register my own block as a heading source, in order that content built with my block isn't silently left out of visitors' tables of contents.

[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.