Skip to content

Make Document Outline (Content Structure) Extensible for Custom Blocks #71699

@lukasniebler

Description

@lukasniebler

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:

  1. You create a dynamic block that renders an <h2> inside its output.
  2. The heading is visible on the frontend.
  3. 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

/**
* 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 ),
} ) );
};

const headings = useMemo(
() => computeOutlineHeadings( blocks ),
[ blocks ]
);

Similar Issues (but not identical)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Needs DecisionNeeds a decision to be actionable or relevant[Feature] Document OutlineAn option that outlines content based on a title and headings used in the post/page[Feature] ExtensibilityThe ability to extend blocks or the editing experience[Type] EnhancementA suggestion for improvement.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions