Refactor Table of Contents server rendering#80098
Conversation
|
Size Change: -9 B (0%) Total Size: 7.69 MB 📦 View Changed
|
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
There was a problem hiding this comment.
Pull request overview
This PR refactors core/table-of-contents so its front-end output is rebuilt on the server from the current post content at render time, avoiding stale saved TOC markup and enforcing predictable behavior when the block is used in templates.
Changes:
- Rebuild TOC entries in PHP by scanning the current post’s block content (including synced patterns and template parts) and extracting heading text/anchors from rendered heading HTML.
- Gate template rendering so TOC only renders for singular views when the active template contains a
core/post-contentblock (including via nested template parts). - Add dedicated PHPUnit and Playwright e2e coverage for server-rendered behavior, including pagination and template boundary rules.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
packages/block-library/src/table-of-contents/index.php |
Implements server-side heading resolution and TOC HTML generation with template/post-content boundary checks. |
phpunit/blocks/render-block-table-of-contents-test.php |
Adds PHPUnit coverage for synced patterns, template parts, pagination, and template boundary detection. |
test/e2e/specs/editor/blocks/table-of-contents-server-rendering.spec.js |
Adds e2e coverage for server-rendered TOC behavior across post content and template scenarios. |
| public function tear_down() { | ||
| unset( $GLOBALS['_wp_current_template_content'] ); | ||
| wp_reset_postdata(); | ||
| parent::tear_down(); | ||
| } |
|
Flaky tests detected in 8d00c0d. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29088974141
|
What
Refactors the front-end/server rendering for the Table of Contents block so it builds its entries from the current post content at render time.
The renderer now uses the
core/post-contentboundary to decide which headings are eligible when the block is placed in a template, and it supports headings from core Heading blocks, synced patterns, and template parts within that boundary.Why
The saved Table of Contents markup can become stale when post headings change. Server rendering should reflect the current front-end post content without relying on editor-side heading observation or changing the editor implementation.
The block also needs predictable template behavior: when placed in a template, it should render from the current post’s content only if that template contains a
core/post-contentblock. It should not scan unrelated template headings or arbitrary site template content.How
WP_Block_Processorto walk block content and resolve supported nested content sources.WP_HTML_Tag_Processorto read heading text and existing heading anchors from rendered Heading block HTML.ariaLabel,ordered,maxLevel, andonlyIncludeCurrentPage.Testing Instructions
Start the test environment:
Run the focused e2e coverage:
Run the focused PHPUnit coverage:
Optional manual check:
core/post-content.core/post-content.core/post-content.