-
Notifications
You must be signed in to change notification settings - Fork 4.7k
Description
What problem does this address?
The Document Outline (Content Structure) feature in the Block Editor currently only includes core/heading blocks when generating its table of contents (ToC). This means custom blocks that output heading elements are ignored.
We need a way to extend the list of headings considered by the Document Outline, so developers creating custom blocks with headings can integrate them into the content structure analysis.
Problem
Right now, there is no filter or API hook to let developers register their custom blocks as contributing headings to the Document Outline or word/character counts.
Current behavior:
Only headings from core/heading are counted and displayed.
Paragraph and word counts also ignore text from dynamic or custom blocks.
Blocks that output <h1>–<h6> markup are completely invisible in the Document Outline, making it misleading or incomplete.
Example Use Case:
- You create a dynamic block that renders an
<h2>inside its output. - The heading is visible on the frontend.
- But the Document Outline ignores it entirely, as if it doesn't exist.
What is your proposed solution?
Introduce a filter or extensibility point inside the DocumentOutline component so developers can inject additional headings.
The current code
gutenberg/packages/editor/src/components/document-outline/index.js
Lines 76 to 93 in 61e6141
| /** | |
| * Returns an array of heading blocks enhanced with the following properties: | |
| * level - An integer with the heading level. | |
| * isEmpty - Flag indicating if the heading has no content. | |
| * | |
| * @param {?Array} blocks An array of blocks. | |
| * | |
| * @return {Array} An array of heading blocks enhanced with the properties described above. | |
| */ | |
| const computeOutlineHeadings = ( blocks = [] ) => { | |
| return blocks | |
| .filter( ( block ) => block.name === 'core/heading' ) | |
| .map( ( block ) => ( { | |
| ...block, | |
| level: block.attributes.level, | |
| isEmpty: isEmptyHeading( block ), | |
| } ) ); | |
| }; |
gutenberg/packages/editor/src/components/document-outline/index.js
Lines 150 to 153 in 61e6141
| const headings = useMemo( | |
| () => computeOutlineHeadings( blocks ), | |
| [ blocks ] | |
| ); |
Similar Issues (but not identical)
- Table of Contents does not include headings not added as heading blocks #5037 – Describes the same issue within the ToC Block (but not the document overview)
- Table of content not counting custom blocks #28607 - Describes the issue with the words / paragraph count in the document overview - But not the missing extendability for headlines.