Feature: Adding support for more granular controls over the ToC block #69063

gmovr · 2025-02-05T19:29:50Z

What?

It allows a user more control over the ToC block.
- They can choose how deep they want the ToC to be (just h2? all the way to h6?)
- Additionally, we allow the user to explicitly exclude a given heading by giving the heading a class of toc-exclude. This will exclude it from the ToC, even if the given settings for heading level would qualify it. Removed as out of scope.

Why?

On several sites, the ToC block is too rigid, and we're forced to convert it to a static list. This is subpar, as it loses the logic, and a changed heading will lead to a broken link reference.

How?

It gives the user simple controls for choosing how many levels they need. This may differ from one page to another.
~~The exclude feature is necessary, as some users may want to include headings for SEO purposes, that are not necessarily wanted in the ToC.~~

Testing Instructions

Check out the branch.
Open a new post or page.
Add multiple headings of different levels.
Add a ToC block.
Ensure that the settings are correctly picking the right headings.
Test the toc-exclude class on a heading.

Just like a TV cooking show, I've prepared some code you can paste into the editor to test this:

<!-- wp:table-of-contents {"headings":[{"content":"This is the intro","level":2,"link":"http://localhost:8082/?p=5#this-is-the-intro"},{"content":"Another H2","level":2,"link":"http://localhost:8082/?p=5#another-h2"},{"content":"H3 one more time","level":2,"link":"http://localhost:8082/?p=5#h3-one-more-time"}],"includeAllHeadings":false,"maxLevel":2} -->
<nav class="wp-block-table-of-contents"><ol><li><a class="wp-block-table-of-contents__entry" href="http://localhost:8082/?p=5#this-is-the-intro">This is the intro</a></li><li><a class="wp-block-table-of-contents__entry" href="http://localhost:8082/?p=5#another-h2">Another H2</a></li><li><a class="wp-block-table-of-contents__entry" href="http://localhost:8082/?p=5#h3-one-more-time">H3 one more time</a></li></ol></nav>
<!-- /wp:table-of-contents -->

<!-- wp:heading -->
<h2 class="wp-block-heading" id="this-is-the-intro">This is the intro</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading" id="another-heading-here">Another heading here</h3>
<!-- /wp:heading -->

<!-- wp:heading -->
<h2 class="wp-block-heading" id="another-h2">Another H2</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading" id="h3-again">H3 again</h3>
<!-- /wp:heading -->

<!-- wp:heading {"level":4} -->
<h4 class="wp-block-heading" id="what-about-a-h4">What about a h4?</h4>
<!-- /wp:heading -->

<!-- wp:heading -->
<h2 class="wp-block-heading" id="h3-one-more-time">H3 one more time</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":4} -->
<h4 class="wp-block-heading" id="h4-it">h4 it</h4>
<!-- /wp:heading -->

<!-- wp:heading {"level":5} -->
<h5 class="wp-block-heading" id="even-a-h5">Even a h5</h5>
<!-- /wp:heading -->

<!-- wp:heading {"level":6} -->
<h6 class="wp-block-heading" id="or-a-h6">...or a h6</h6>
<!-- /wp:heading -->

<!-- wp:heading {"className":"toc-exclude"} -->
<h2 class="wp-block-heading toc-exclude" id="this-one-is-hidden-though">This one is hidden though</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph -->

Testing Instructions for Keyboard

We use standard components only adding a standard select box.

Screenshots or screencast

Before	After

github-actions · 2025-02-05T19:30:08Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @jodamo5.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: jodamo5.

Co-authored-by: gmovr <etobiesen@git.wordpress.org>
Co-authored-by: swissspidy <swissspidy@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: mrfoxtalbot <mrfoxtalbot@git.wordpress.org>
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>
Co-authored-by: JosVelasco <josvelasco@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2025-02-05T19:30:30Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @gmovr! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

mrfoxtalbot · 2025-02-06T14:55:46Z

I tested it using Playgound, and it works as expected.

Kapture.2025-02-06.at.15.50.21.mp4

swissspidy · 2025-02-10T13:53:23Z

The last design guidance on #51605 is from 2023, so I think we need a fresh perspective there. The toggle + dropdown seems a bit unnecessary to me.

Either way, I don't think we need two attributes for this. includeAllHeadings: true is equal to maxLevel: 6 anyway, so that's just redundant. If we want to keep the toggle + dropdown combo, then I would simply use maxLevel: null or so for the toggled-on state. In other words: we can implement this with only the maxLevel attribute.

swissspidy · 2025-02-10T13:55:29Z

packages/block-library/src/table-of-contents/edit.js

+							] }
+							onChange={ ( value ) =>
+								setAttributes( {
+									maxLevel: parseInt( value, 10 ),


FYI passing radix 10 isn't needed and hasn't been for like 10 years. parseInt( value ) is enough

swissspidy · 2025-02-10T13:57:30Z

Additionally, we allow the user to explicitly exclude a given heading by giving the heading a class of toc-exclude. This will exclude it from the ToC, even if the given settings for heading level would qualify it.

Where is this coming from? I don't see a feature request for it.

IMHO this is better discussed in a new issue first before trying to add this in via this PR.

There might be alternative approaches for this, e.g. with a new attribute on the heading block, or with a different class name or so. Hence best to split this up.

gmovr · 2025-02-10T13:58:55Z

Additionally, we allow the user to explicitly exclude a given heading by giving the heading a class of toc-exclude. This will exclude it from the ToC, even if the given settings for heading level would qualify it.

Where is this coming from? I don't see a feature request for it.

IMHO this is better discussed in a new issue first before trying to add this in via this PR.

There might be alternative approaches for this, e.g. with a new attribute on the heading block, or with a different class name or so. Hence best to split this up.

Thanks for the feedback. This is coming from my own use wihin the team that update our blog. Often we do not want certain headings in the ToC, and to accomplish this now, we need to convert it to a static list.

I was considering setting it on the heading block, but it felt a bit inverse in this case, as most pages will have headings while fewer will have the ToC block. So IMO the ToC block should contain ToC logic.

I'm open to either approach, though, or moving it to an issue and a subsequent PR. :)

gmovr · 2025-02-10T13:59:59Z

The last design guidance on #51605 is from 2023, so I think we need a fresh perspective there. The toggle + dropdown seems a bit unnecessary to me.

Either way, I don't think we need two attributes for this. includeAllHeadings: true is equal to maxLevel: 6 anyway, so that's just redundant. If we want to keep the toggle + dropdown combo, then I would simply use maxLevel: null or so for the toggled-on state. In other words: we can implement this with only the maxLevel attribute.

That makes sense! I will change the filtering logic.

swissspidy · 2025-02-10T14:39:50Z

Additionally, we allow the user to explicitly exclude a given heading by giving the heading a class of toc-exclude. This will exclude it from the ToC, even if the given settings for heading level would qualify it.

Where is this coming from? I don't see a feature request for it.
IMHO this is better discussed in a new issue first before trying to add this in via this PR.
There might be alternative approaches for this, e.g. with a new attribute on the heading block, or with a different class name or so. Hence best to split this up.

Thanks for the feedback. This is coming from my own use within the team that update our blog. Often we do not want certain headings in the ToC, and to accomplish this now, we need to convert it to a static list.

I was considering setting it on the heading block, but it felt a bit inverse in this case, as most pages will have headings while fewer will have the ToC block. So IMO the ToC block should contain ToC logic.

I'm open to either approach, though, or moving it to an issue and a subsequent PR. :)

To clarify, my suggestion was not necessarily to do the inverse, but for example to introduce a proper toggle on the heading block that the TOC block could then use. I would also take a look at how Google Docs does this for example. You can remove a heading from the TOC simply by clicking on an "X" next to it.

That's why I think this needs its own issue & discussion first.

gmovr · 2025-03-19T10:08:42Z

@swissspidy -- I've implemented your suggestions for the heading-level filtering. Could you take another look, please? Thanks

swissspidy

I think it looks good, but I'd like others to chime in who are more active in this component.

juanmaguitar · 2025-03-27T13:33:47Z

@ZebulanStanphill could you have a look at this PR?
I think you worked on this block in the past

Mamaduka

Thank you, @gmovr!

The implementation looks good; I just have a couple of minor suggestions.

I think the maxLevel solution makes more sense here, compared to the allowed levels, where the user can specify exactly which levels to display.

packages/block-library/src/table-of-contents/block.json

packages/block-library/src/table-of-contents/hooks.js

…, such as heading level, and the option for excluding certain headings via a css class

…cluding all heading levels. Rebuild docs.

…l value in the filtering logic

gmovr · 2025-03-27T14:35:39Z

@Mamaduka --- Thanks for the suggestion. That's a better way of doing it, and I've done the changes now. Could you take another look?

I also rebased it on top of the latest trunk, just in case, as this branch is getting a bit old.

Mamaduka

Thank you, @gmovr!

We need to do a bit cleanup after switching to undefined, but besides that everything looks great ✅

P.S. Running npm run fixtures:regenerate should fix failing JS unit tests.

packages/block-library/src/table-of-contents/edit.js

gmovr · 2025-03-27T15:27:31Z

Thanks! There's one more issue now, if you change the heading level, the save button does not become enabled, I wonder if it is due to a missing default value, or do we need to persist this data?

Doing an edit in the editor will sort it, and the change is carried over, but changing this setting just by itself isn't seen as a "saveable" change by the editor. 🤔

Mamaduka · 2025-03-27T15:35:15Z

I believe that's the same issue as #67583 and urelated to this PR.

Unfortunately, problems like that are the reason the block is still experimental.

gmovr · 2025-03-27T15:37:01Z

I believe that's the same issue as #67583 and urelated to this PR.

Unfortunately, problems like that are the reason the block is still experimental.

Thanks! That makes see :)

Mamaduka · 2025-03-27T16:50:36Z

Coincidentally, I think I realized how to fix that bug - #69734. Thanks for the reminder, @gmovr :)

gmovr · 2025-03-27T19:13:28Z

Coincidentally, I think I realized how to fix that bug - #69734. Thanks for the reminder, @gmovr :)

That's great, happy to help review it!

…WordPress#69063) Unlinked contributors: jodamo5. Co-authored-by: gmovr <etobiesen@git.wordpress.org> Co-authored-by: swissspidy <swissspidy@git.wordpress.org> Co-authored-by: Mamaduka <mamaduka@git.wordpress.org> Co-authored-by: mrfoxtalbot <mrfoxtalbot@git.wordpress.org> Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org> Co-authored-by: JosVelasco <josvelasco@git.wordpress.org> Co-authored-by: jasmussen <joen@git.wordpress.org>

gmovr requested review from ZebulanStanphill, ajitbohra, juanmaguitar, fabiankaegy and ndiego as code owners February 5, 2025 19:29

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Feb 5, 2025

Mamaduka added [Type] Enhancement A suggestion for improvement. [Block] Table of contents (experimental) Affects the Table of contents Block labels Feb 6, 2025

swissspidy added the Needs Design Feedback Needs general design feedback. label Feb 10, 2025

swissspidy reviewed Feb 10, 2025

View reviewed changes

gmovr mentioned this pull request Feb 14, 2025

Improvement: A user should be able to exclude headings from the ToC block in the editor. #69200

Open

swissspidy requested review from Mamaduka and swissspidy March 22, 2025 16:00

swissspidy approved these changes Mar 22, 2025

View reviewed changes

Mamaduka reviewed Mar 27, 2025

View reviewed changes

packages/block-library/src/table-of-contents/block.json Outdated Show resolved Hide resolved

packages/block-library/src/table-of-contents/hooks.js Outdated Show resolved Hide resolved

gmovr added 5 commits March 27, 2025 15:22

Feature: Adding support for more granular controls over the ToC block…

779e495

…, such as heading level, and the option for excluding certain headings via a css class

Chore: upgrade integration tests and fixtures to accept new attribute

a0c39b9

Refactor: Rely on nullable maxlevel instead of a separate prop for in…

d33f3a1

…cluding all heading levels. Rebuild docs.

Remove: toc-exclude class functionality. Out of scope.

587d760

Leaving out default value, and checking for definition instead of nul…

89dc817

…l value in the filtering logic

gmovr force-pushed the improve-toc-block-with-granularity branch from a27020a to 89dc817 Compare March 27, 2025 14:33

gmovr added 2 commits March 27, 2025 15:38

Update JSdoc in edit.js

8bfdbfa

Fix null check in edit.js for settings panel

4f19708

Mamaduka approved these changes Mar 27, 2025

View reviewed changes

gmovr added 4 commits March 27, 2025 16:19

Additonal checks null => undefined

fc87fc8

One more check for onDeselect

7b61add

And for resetAll

bed0e60

Regenerate text fixtures

2461668

Mamaduka merged commit 1291719 into WordPress:trunk Mar 27, 2025
59 checks passed

github-actions bot added this to the Gutenberg 20.6 milestone Mar 27, 2025

gmovr mentioned this pull request Mar 27, 2025

ToC: Fix related block attribute persistence #69734

Merged

mrfoxtalbot mentioned this pull request May 30, 2025

Feature: Allow user to exclude headings from the ToC block in the editor. #70235

Closed

Feature: Adding support for more granular controls over the ToC block #69063

Feature: Adding support for more granular controls over the ToC block #69063

Uh oh!

Conversation

gmovr commented Feb 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Uh oh!

github-actions bot commented Feb 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

github-actions bot commented Feb 5, 2025

Uh oh!

mrfoxtalbot commented Feb 6, 2025

Uh oh!

swissspidy commented Feb 10, 2025

Uh oh!

swissspidy Feb 10, 2025

Choose a reason for hiding this comment

Uh oh!

swissspidy commented Feb 10, 2025

Uh oh!

gmovr commented Feb 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmovr commented Feb 10, 2025

Uh oh!

swissspidy commented Feb 10, 2025

Uh oh!

gmovr commented Mar 19, 2025

Uh oh!

swissspidy left a comment

Choose a reason for hiding this comment

Uh oh!

juanmaguitar commented Mar 27, 2025

Uh oh!

Mamaduka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gmovr commented Mar 27, 2025

Uh oh!

Mamaduka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gmovr commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mamaduka commented Mar 27, 2025

Uh oh!

gmovr commented Mar 27, 2025

Uh oh!

Uh oh!

Mamaduka commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmovr commented Mar 27, 2025

Uh oh!

Uh oh!

gmovr commented Feb 5, 2025 •

edited

Loading

github-actions bot commented Feb 5, 2025 •

edited

Loading

gmovr commented Feb 10, 2025 •

edited

Loading

gmovr commented Mar 27, 2025 •

edited

Loading

Mamaduka commented Mar 27, 2025 •

edited

Loading