Table of Contents does not include headings not added as heading blocks

[briandeconinck]

Issue Overview

I don't think I've seen this in any existing issues. This is a relatively small issue, but definitely something that shouldn't fall through the cracks.

There are three supported ways to add headings to a post:

• By adding a Heading block
• By adding a Classic editor block which contains headings in its contents
• By adding a Custom HTML block and hand-coding an <h2>, <h3>, etc.

It's easy to imagine plugins adding their own blocks that include headings in their markup (including, hopefully, a heading-level selector to choose the right type of heading).

The Table of Contents/Document Outline generates an outline of the structure of the document, which is enormously useful to help content creators build accessible content. However, the ToC only contains headings added as Heading blocks.

Not sure how the ToC is being generated, but it should give a complete picture of the heading structure of the post---any headings in the post markup, as end-users will experience it. Otherwise, content creators who come to rely on the ToC feature may unwittingly give their posts poor or confusing structure.

Steps to Reproduce (for bugs)

1. Create a new post using Gutenberg.
2. Add a Heading block, H2: "Heading 2 in a Heading block"
3. Add a Classic editor block, H2: "Heading 2 in a Classic Editor block"
4. Add a Custom HTML block, and code a <h2>Heading 2 in a Custom HTML block</h2>.
5. Open the Table of Contents (right-hand sidebar) or the Document Outline (top left-hand corner of the editor, in the Content Structure button.

This is in Gutenberg v2.1.0, WP v4.9.4, Google Chrome v64.

Expected Behavior

The Table of Contents should show the document title followed by three H2 headings.

Current Behavior

The Table of Contents shows the document title followed by just one H2 heading, "Heading 2 in a Heading block."

Screenshots / Video

[youknowriad]

The Table of contents looks specifically to the presence of some defined blocks. I'd consider this a minor enhancement, but having a generic API to add items to the table of contents seems legit.

[karmatosed]

Let's move this to the ideas project, we are using that to store 'after release' ideas that could be good to work on.

[mrwweb]

@karmatosed @youknowriad It seems odd that this issue is closed, since it's still an problem and feels very much like a bug (the title could be rewritten to read "Document Outline only includes heading blocks when it should include all headings"). This is related to #33079 where the outline doesn't see Reusable Blocks. I'm currently working on an accordion block where I would expect the headings (output into the post content via the save function) to be included in the Document Outline.

It seems that this getting closed has meant it won't get any attention. Can it be reopened since it's still an issue?

[youknowriad]

@mrwweb Right now the headings/blocks highlighted are hardcoded, if we want third-party (and reusable blocks) support, we'd need a dedicated Block API potentially that takes all of the use-cases into consideration.

[mrwweb]

@youknowriad Thanks for reopening! I hope this can get some eyes on it in the coming versions!

I wonder if it would be possible to make the outline by parsing the rendered editor contents? Between the Classic block, HTML block, Reusable Blocks, and 3rd-party blocks, it seems that making this change would likely make the outline more useful in a significant number of cases and also help highlight heading outline problems more frequently.

[Taruks]

Yes, definitely it would be very helpful and important for SEO optimisation reasons having a complete heading structure of the post. Would be great to see it implemented.
Thanks

[leogitdev]

I'm writing a custom heading block that can have h2~h6 tags and I think it's unfortunate that there's no way for them to show in the document outline in the sidebar.