Templates: Let a template be rendered inside another template - #85402

What?

Lets a template be rendered inside another template, the way a page is rendered inside the template assigned to it.

A template names the template it is rendered inside, and the parent's Content block (core/post-content) is the slot: the child template's blocks are rendered in it. A 404 template can then carry only the "nothing here" message, while the header, the footer and whatever else surrounds it live in a single template.

A theme names it for its own templates in the new templates section of its theme.json, so a theme works that way on activation with nothing to set up. A site overrides what the theme names, including rendering a template on its own, from the Site Editor.

Behind the gutenberg-template-inheritance experiment, while the product questions this opens are settled: named slots, what a theme may declare, and how a chain meets the template hierarchy.

Why?

Every template repeats its own header and footer today. Changing the shell of a site means editing every template that has one, and a template that only differs in its main content still has to restate everything around it.

How?

A theme declares it:

"templates": [
	{ "name": "404", "template": "layout" },
	{ "name": "search", "template": "layout" }
]

A site's own choice, stored in the _wp_page_template post meta of the template's post — the same meta a page uses for the same purpose — stands for the one the theme names. The meta is default when the site renders the template on its own and absent when the site has made no choice, so reverting a template to the one of the theme drops the choice with it. The REST field is named template, like the one a post carries.

• lib/experimental/block-template-parent.php holds the server side, loaded only with the experiment:
  • The slot. The first core/post-content block in document order, at whatever depth, takes the child's blocks as its own inner blocks rather than being replaced by them, so it still renders its wrapper: its layout, its alignment and entry-content apply to the template rendered inside it, and the canvas and the front end agree. It is marked with a templateSlot attribute in the markup, and a register_block_type_args filter makes the block render those blocks instead of the post of the request.
  • The resolution, on template_include once locate_block_template() has settled on a template. It walks the chain, stopping at a template that names none, at one already in the chain, and at one with no slot. The templates locate_block_template() already read are reused, so a site that uses none of this pays no extra query; they are forgotten when a template's post cache is cleaned.
  • Two REST fields on wp_template: template, the slug it is rendered inside, validated against the templates it may name, and has_content_slot, whether it has a slot of its own.
• templates is a new top-level theme.json section: added to the schema, to WP_Theme_JSON_Gutenberg::VALID_TOP_LEVEL_KEYS, and read through a new get_templates() beside get_template_parts().
• packages/core-fields/src/wp_template/template/ is the Template field of a template. The choices leave out the template itself, every template already rendered inside it, and every template with no slot. The field belongs to @wordpress/core-fields, which is core code with no experiment to read, so it is unregistered while the experiment is off and the template summary form leaves it out.
• The editor renders the parent around the template under "Show template", the same control a page has. getTemplateId() answers the template a template is rendered inside, and the provider gives the parent's Content block the template being edited as its context, so the blocks in the slot edit the child rather than the parent.

A Content block inside a query loop is not the slot. It belongs to the post that loop is rendering, so putting the child there would repeat it once per post. The editor leaves those out of the post content blocks it makes editable for the same reason. This is why index.html as themes ship it cannot be a parent: its only Content block is inside the Query Loop.

Testing Instructions

0. Enable the inherted templates experiment
1. Use the version of TT5 in Twenty Twenty-Five: Render every template inside a shared index template
2. Open the 404 template and see that Template is set to index.
3. Open the preview menu (the screen icon) and tick Show template: the canvas shows Layout around the 404 content, and only the 404 content is editable. Type in it and confirm the 404 template, not Layout, becomes dirty.
4. Save, then visit a URL that does not exist. The 404 content renders inside Layout, in the Content block's own wrapper.
5. Open index and confirm its Template options leave out Page: 404 and index itself, so no loop can be made, and leave out Blog Home, All Archives and Search Results, whose only Content block is inside a Query Loop.
6. Set the 404 template's Template back to None, save, and confirm the front end renders it on its own again.
7. Turn the experiment off and confirm the Template row is gone from the template summary and the front end renders every template on its own.

To check what a theme declares, add a templates section to the theme.json of a block theme, pointing one of its templates at another, and confirm the front end and the summary both follow it with nothing set in the editor.

Screenshots or screencast

Use of AI Tools

Authored with Claude Code (Opus 5), directed and reviewed by me. The tests were written before the implementation and verified failing first. The front end and the editor flows were checked by hand in WordPress Playground; the end to end spec has not been run, as Docker would not start in that environment, so its selectors were pinned against the running editor rather than by executing it.