Table of Contents: add support for third party heading blocks or a way for third party blocks to indicate headings

[techmagick]

TOC block, like the block editor outline view does NOT recognized 3rd party heading blocks.
This makes the TOC block useless for those who use other blocks, like generateblocks, spectra, kadence, and others.

[techmagick]

TOC example -

[Mamaduka]

Thanks for the feedback, @techmagick!

The ToC block is still experimental and only ships with the Gutenberg plugin. Here's the tracking issue for stabilization - #42229.

Out of curiosity, what's the reason for using third-party heading blocks?

[gziolo]

That's an interesting consideration of how custom blocks could inform that they are willing to tap into the logic that is today reserved for the core's Heading block. I believe that there are more places where the Heading block is used to show some information in the editor's UI.

[colorful-tones]

I'm curious to hear more about the intention and use cases here. I want to clarify that I have not used any of the 3rd-party plugins mentioned. @techmagick, do you want the ability to use WordPress blocks and 3rd-party block all mixed and have the WordPress core block recognize every heading h1 - h6 within the block editor? I guess if all the 3rd-party plugins register and save their block definitions to WordPress specs then it could be reasonable. 🤔

I would hate to see progress on the overall Table of Contents block for WordPress slow or diverge wildly while trying to accommodate a bunch of 3rd-party plugins. I mostly just want to make sure we're being clear as to what we mean by 3rd party headings. How are these 3rd-party heading blocks being registered and rendered?

[dougwollison]

Was just about to write a feature request related to this. For me it's custom blocks needing to appear in the Document Outline, but Table of Contents should use similar logic.

Every site I build ends up including at least one custom block (usually the accordion) that provides it's own heading, which currently isn't detected by the Document Outline. The user can adjust the heading level of the accordion to match the hierarchy of their content, but it's difficult to keep track of what level is appropriate and the outline doesn't reflect the true structure. I ended up slapping together a plugin that offers it's own version of the Document Outline, but with buttons to quickly edit the level of each heading, individually or in bulk (shift up/down, and a "fix all" if inappopriate levels are detected).

My suggestion, which is similar to how my plugin opperates, is to define a block support, the config of which provides the following:

• Which attribute defines the heading level (defaults to "level")
• Which attribute defines the label (could just rely on __experimentalLabel instead once that graduates)
• Wether or not the children are "scoped", meaning that any heading-type blocks within should be of a lower level than the block itself (can't think of an example that would need this turned off, but would be nice to have control over)

For a quick and dirty example:

{
    "name": "my/accordion",
    "attributes": {
        "level": {
            "type": "number",
            "default": 3
        }
        "title": {
            "type": "string",
            "source": "html",
            "selector": ".my-accordion__title"
        },
    },
    "supports": {
        "documentOutline": {
            "levelAttribute": "level",
            "labelAttribute": "title",
            "scopesContents": true
        }
    }
}

Granted, this is only viable with "simple" blocks that provide a single heading each, but I think offering a filter on the a getOutline() API would allow any weirder examples to splice in their additional hiearchy, and could be a phase 2 of this feature.

[lukasniebler]

I am also looking for a way to influence the outline tab (and the new TOC-Block).

Similar to @dougwollison we also developed our own nested accordion block which uses heading levels inside the output who are currently not detected by the document outline feature.

It would be great if there is a way to signal the BlockEditor that the block has a certain Heading level via the block.json or register function like Doug suggested. For example I am already using the __experimentalLabel Feature inside my custom block to change the list view and it already works like a charm to display the headline texts of our users inside the list view of the editor.

[annezazu]

Jumping back into this issue after chatting about it today on a WP Freelancer call with @techmagick. Thanks again for opening it. Updating the title so it's a bit easier to find and get a sense of what the options are at a glance too (I had a hard time finding the issue quickly). If I got that wrong, feel free to update further.

I wanted to note too that since this has been opened, an effort was started and paused around canonical blocks #58773 of which the Table of Contents block was noted for consideration. Work still remains to stabilize and release this block #42229. I'm curious to hear from more folks in @WordPress/outreach around the impact of this issue and how it should be considered when it comes to eventually shipping a v1 of this block.

[gziolo]

I was looking at this issue again, and I thought that we could use supports to annotate custom blocks (Heading block in core, too) to let the editor know that they have special semantic meaning. So the #54646 (comment) from @dougwollison is spot on and it's very close to what we would offer, in particular this part:

 {
    "supports": {
        "documentOutline": {
            "levelAttribute": "level",
            "labelAttribute": "title",
            "scopesContents": true
        }
    }
}

Great observation that we would need to tell which attribute maps to the what the Heading block provides through the level attribute which is the number in the range 1-6. Some of the features that depend on that are collected on this screenshot:

I have an impression that in the past we would also show the somewhere the total count of headings, but maybe it isn't a thing anymore.