[youknowriad]

What?

Closes #80784 and Part of #42229. An alternative to #80950.

The Table of Contents block now finds the post whose headings it lists through the postId block context, both on the server and in the editor. As a result, a table of contents placed once in a template (e.g. Single) lists the headings of whichever post is being viewed.

Why?

Today the front end only renders inside the_content, so a table of contents in a template renders nothing. In the editor, the block scans every block on screen, which in a template means the template's own blocks. Block context is the standard way blocks like Post Title or Post Content find "the current post", and it covers the post editor, templates, and Query Loops the same way.

It also makes the block simpler: the editor no longer subscribes to every store change and writes a headings attribute back into the block.

How?

Front end (index.php)

• Use $block->context['postId'] instead of get_post() inside the_content.
• Outside post content, only render on singular views. Core fills postId from the global post for top-level blocks, which on archives is the first post in the list.
• Render nothing for password-protected posts.

Editor (hooks.js, edit.jsx)

• Read the post's edited blocks with useEntityBlockEditor( 'postType', postType, { id: postId } ), the same source the Post Content block uses. It includes unsaved edits and shares the parse cache, so the blocks are the same objects the editor shows.
• Walk the blocks in document order. The previous getClientIdsOfDescendants walk went level by level, so nested headings could be listed out of order compared with the front end.
• The permalink comes from the post record's link instead of reading core/editor by string.
• Without a postId, show a template placeholder. When the editor provides a postType (single, page, single-{type} templates) it explains that headings come from the post being viewed. Otherwise (archive, search, 404, …) it says the block needs a single post or page.
• Remove the headings attribute. It is role: local, never saved, and older saved markup still migrates through the existing v1 deprecation, which matches on the saved <nav> markup.
• The inserter example now shows the placeholder, since a preview has no post to read.

Known limitations

• Custom templates with arbitrary slugs don't get a postType from the editor, so they show the "needs a single post or page" placeholder even when they are assigned to posts. The front end works for them.
• A template-level table of contents links only to headings that have anchors. Headings written without a table of contents in the post don't get auto-generated anchors (the remaining fixme e2e test). That needs a separate anchor strategy.

Testing Instructions

1. Enable experimental blocks, then in the Site Editor add a Table of Contents block above Post Content in the Single template.
2. Confirm the block explains that it will show headings from the post being viewed.
3. View two posts with different headings on the front end and confirm each lists its own headings.
4. Add the block to the Archive template, confirm the "needs a single post or page" placeholder, and confirm nothing renders on an archive page.
5. In the post editor, add a Table of Contents block and headings, then edit, reorder and nest headings in a Group. Confirm the list updates live and in document order.

Automated:

• npm run test:e2e -- test/e2e/specs/editor/blocks/table-of-contents.spec.js: four template tests are switched on in this PR. I couldn't run them locally because they need a build.
• npm run test:unit:php:base -- --filter Tests_Blocks_Render_Table_Of_Contents_Test: passes locally (12 tests), including new tests for singular views, archives and password-protected posts.
• The block fixture tests pass.

🤖 Generated with Claude Code

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: mikachan <mikachan@git.wordpress.org>
Co-authored-by: adrianduffell <adrianduffell@git.wordpress.org>
Co-authored-by: bgardner <bgardner@git.wordpress.org>
Co-authored-by: im3dabasia <im3dabasia1@git.wordpress.org>
Co-authored-by: getdave <get_dave@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: -289 B (0%)

Total Size: 8.95 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-library/index.min.js	442 kB	-289 B (-0.07%)

_{cf41643 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	cecab2a	trunk	% Change
timeToFirstByte	43.35 ms +6.46% -5.54%	42.3 ms +4.96% -0.95%	2.48%
largestContentfulPaint	74 ms +5.41% -8.11%	74 ms +5.41% -2.7%	0%
lcpMinusTtfb	28.65 ms +5.93% -3.66%	29.95 ms +13.86% -6.68%	-4.34%
wpBeforeTemplate	22.62 ms +12.82% -3.63%	22.14 ms +8.94% -0.81%	2.17%
wpTemplate	16.13 ms +8.56% -3.66%	16.74 ms +2.33% -2.33%	-3.64%
wpTotal	40.08 ms +6.06% -6.31%	39.06 ms +4.79% -1.41%	2.61%
wpMemoryUsage	7.65 MB +0% -0%	7.61 MB +0% -0%	0.56%
wpDbQueries	16 +0% -0%	16 +0% -0%	0%

front-end-classic-theme

Metric	cecab2a	trunk	% Change
timeToFirstByte	32.3 ms +7.59% -1.7%	36.1 ms +5.4% -3.88%	-10.53%
largestContentfulPaint	72 ms +5.56% -0%	80 ms +2.5% -0%	-10%
lcpMinusTtfb	40 ms +3.13% -3.75%	44.7 ms +2.13% -1.79%	-10.51%
wpBeforeTemplate	19.94 ms +7.42% -1.96%	19.57 ms +3.58% -1.64%	1.89%
wpTemplate	9.56 ms +4.39% -3.56%	13.24 ms +2.64% -3.78%	-27.79%
wpTotal	29.65 ms +8.4% -1.18%	33.1 ms +5.92% -3.35%	-10.42%
wpMemoryUsage	6.22 MB +0% -0%	6.29 MB +0% -0%	-1.07%
wpDbQueries	9 +0% -0%	13 +0% -0%	-30.77%

media-processing

Metric	cecab2a	trunk	% Change
mediaProcessingJpeg	328.09 ms +0.84% -0.37%	323.37 ms +0.17% -0.42%	1.46%
mediaProcessingAvif	4798.55 ms +0.22% -0.12%	4842.72 ms +0.3% -0.22%	-0.91%
mediaProcessingJpegToAvif	3355.2 ms +0.28% -0.37%	3369.51 ms +0.34% -0.12%	-0.42%

media-upload

Metric	cecab2a	trunk	% Change
jpegUploadProcessing	1413.28 ms +0.8% -0.25%	1411.88 ms +1.24% -0.39%	0.1%
pngUploadProcessing	189.44 ms +4.76% -2.6%	184.53 ms +12.51% -2.32%	2.66%
largeJpegUploadProcessing	1399.92 ms +1.13% -0.62%	1400.18 ms +1.18% -0.71%	-0.02%
multipleImageUploadProcessing	1508.77 ms +4.6% -1.43%	1526.6 ms +0.21% -3.3%	-1.17%

post-editor

Metric	cecab2a	trunk	% Change
serverResponse	420.32 ms +6.54% -7.04%	419.18 ms +3.63% -8.61%	0.27%
firstPaint	460.5 ms +4.6% -38.69%	464.57 ms +3.08% -41.35%	-0.88%
domContentLoaded	1096.69 ms +2.99% -1.77%	1071.09 ms +1.4% -0.9%	2.39%
loaded	1097.75 ms +2.97% -1.76%	1072.46 ms +1.36% -0.91%	2.36%
firstContentfulPaint	483.71 ms +1.73% -1%	470.97 ms +1.72% -1.37%	2.71%
firstBlock	3390.29 ms +3.73% -2.89%	3224.34 ms +0.53% -0.87%	5.15%
type	16.68 ms +2.88% -2.4%	16.85 ms +7.54% -4.63%	-1.01%
typeWithoutInspector	17.05 ms +4.28% -1.7%	16.74 ms +2.57% -3.29%	1.85%
typeWithTopToolbar	22.95 ms +4.27% -3.14%	22.19 ms +6.08% -0.81%	3.42%
typeContainer	8.38 ms +6.09% -2.39%	8.21 ms +14.13% -3.78%	2.07%
focus	120.93 ms +9.78% -5.04%	118.62 ms +4.65% -9.32%	1.95%
firstFocus	226.49 ms +0% -0%	232.12 ms +0% -0%	-2.43%
selectAll	515.78 ms +2.14% -3.29%	506.53 ms +3.4% -4.27%	1.83%
listViewOpen	76.25 ms +13.81% -7.65%	74.22 ms +0.71% -4.72%	2.74%
inserterOpen	41.12 ms +11.24% -5.93%	38.71 ms +13.25% -8.21%	6.23%
inserterHover	11.46 ms +7.42% -6.37%	12.65 ms +4.74% -7.59%	-9.41%
inserterSearch	7.59 ms +11.2% -3.29%	7.92 ms +2.53% -8.21%	-4.17%
loadPatterns	645.36 ms +57.45% -1.4%	635.63 ms +4.47% -2.8%	1.53%
wpTotal	410.61 ms +6.44% -7.24%	408.9 ms +3.6% -8.68%	0.42%
wpMemoryUsage	14.62 MB +0% -0%	13.55 MB +0% -0%	7.88%
wpDbQueries	55 +0% -1.82%	55 +0% -0%	0%

site-editor

Metric	cecab2a	trunk	% Change
serverResponse	309.55 ms +0.68% -9.14%	283.85 ms +6.93% -4.3%	9.05%
firstPaint	213.14 ms +96.83% -8.25%	195.16 ms +111.39% -13.41%	9.21%
domContentLoaded	978.54 ms +2.73% -1.17%	927.6 ms +1.33% -0.97%	5.49%
loaded	979.55 ms +2.71% -1.19%	928.42 ms +1.33% -0.97%	5.51%
firstContentfulPaint	421.22 ms +4.08% -1.26%	397.89 ms +3.93% -7.51%	5.86%
firstBlock	3709.96 ms +0.42% -0.59%	3455.14 ms +0.3% -0.54%	7.38%
type	15.66 ms +1.02% -1.4%	15.46 ms +6.66% -4.59%	1.29%
navigate	88.27 ms +15.82% -4.18%	96.05 ms +13% -4.87%	-8.1%
loadPatterns	985.95 ms +23.56% -13%	1017.67 ms +26.94% -7.56%	-3.12%
loadPages	1058.33 ms +6.57% -1.01%	1039.4 ms +2.18% -0.34%	1.82%
wpTotal	301.15 ms +0.74% -9.44%	275.43 ms +7.23% -4.43%	9.34%
wpMemoryUsage	12.65 MB +0% -0%	12.59 MB +0% -0%	0.45%
wpDbQueries	44 +2.27% -0%	44.5 +1.12% -1.12%	-1.12%

_{cf41643 Run}

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Regression: updating a specific option will only change its value and will not corrupt others in /test/e2e/specs/editor/various/core-settings.spec.js, passed after 1 failed attempt.

Error: expect(received).toStrictEqual(expected) // deep equality

- Expected  - 1
+ Received  + 1

  Array [
    "rewrite_rules",
-   "SERIALIZED DATA",
+   "",
  ]
    at forEach (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:46:26)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:43:35

refuses the drop and uploads nothing in /test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js, passed after 1 failed attempt.

Error: expect(received).toHaveLength(expected)

Expected length: 0
Received length: 1
Received array:  [{"_links": {"about": [{"href": "http://localhost:8889/wp-json/wp/v2/types/attachment"}], "author": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/users/1"}], "collection": [{"href": "http://localhost:8889/wp-json/wp/v2/media"}], "curies": [{"href": "https://api.w.org/{rel}", "name": "wp", "templated": true}], "replies": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/comments?post=246"}], "self": [{"href": "http://localhost:8889/wp-json/wp/v2/media/246", "targetHints": {"allow": ["GET", "POST", "PUT", "PATCH", "DELETE"]}}], "wp:attached-to": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/posts/245", "id": 245, "post_type": "post"}]}, "alt_text": "", "author": 1, "caption": {"rendered": ""}, "class_list": ["post-246", "attachment", "type-attachment", "status-inherit", "hentry", "entry"], "comment_status": "open", "date": "2026-10-19T19:30:07", "date_gmt": "2026-10-19T19:30:07", "description": {"rendered": "<p class=\"attachment\"><a href='http://localhost:8889/wp-content/uploads/2026/10/c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png'><img loading=\"lazy\" decoding=\"async\" width=\"10\" height=\"10\" src=\"http://localhost:8889/wp-content/uploads/2026/10/c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png\" class=\"attachment-medium size-medium\" alt=\"\" style=\"width:100%;height:100%;max-width:10px;\" /></a></p>
"}, "featured_media": 0, "filename": "c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png", "filesize": 80, "guid": {"rendered": "http://localhost:8889/wp-content/uploads/2026/10/c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png"}, "id": 246, "link": "http://localhost:8889/?attachment_id=246", "media_details": {"file": "2026/10/c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png", "filesize": 80, "height": 10, "image_meta": {"alt": "", "aperture": "0", "camera": "", "caption": "", "copyright": "", "created_timestamp": "0", "credit": "", "focal_length": "0", "iso": "0", "keywords": [], "orientation": "0", "shutter_speed": "0", "title": ""}, "sizes": {}, "width": 10}, "media_type": "image", "meta": [], "mime_type": "image/png", "modified": "2026-10-19T19:30:07", "modified_gmt": "2026-10-19T19:30:07", "ping_status": "closed", "post": 245, "slug": "c94b494f-2c0f-4ee3-89b7-3b7bd0a06092", "source_url": "http://localhost:8889/wp-content/uploads/2026/10/c94b494f-2c0f-4ee3-89b7-3b7bd0a06092.png", "status": "inherit", "template": "", "title": {"rendered": "c94b494f-2c0f-4ee3-89b7-3b7bd0a06092"}, "type": "attachment"}]
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js:71:45

_{cf41643 Run}

[bgardner]

Thrilled to see this, hopefully it gets reviewed/merged soon so I can test it out.

[youknowriad]

@bgardner maybe you can test it here and let me know what you think, there's a playground link above https://playground.wordpress.net/?gutenberg-pr=85040

[Mamaduka]

What do you think about returning an empty array here? Then we can avoid useHeadings() ?? [] in the edit component.

[youknowriad]

The robots are dumb sometimes.

[Mamaduka]

This will also close #41031.

@getdave is also exploring a solution to use SSR rendering for the ToC in the editor.

[bgardner]

@youknowriad Appears to be working. See screenshots of post with TOC as well as the Single template:

[mikachan]

This looks like a good simplification! I've left a few minor comments, mostly about the placeholder text.

[mikachan]

Do we need to replicate this in the editor? e.g. show the placeholder when the block is inside a query loop.

[adrianduffell]

Nice, this is testing great for me! Just left an optional suggestion about the instruction text.

[bgardner]

@youknowriad Any idea this will make its way into WordPress 7.2? I just installed Beta 1 and do not see the ToC block yet.

[youknowriad]

The block hasn't been stabilized yet, so it won't be on 7.2