Templates and Template Parts

Block themes arrived in WordPress 5.9 (January 2022) together with the Site Editor. A theme becomes a block theme when it contains templates/index.html; that single file is the minimum template, and it is how WordPress recognises the theme type and enables Appearance > Editor. Some older books place "full site editing" in 5.4 to 5.6; those releases only had Gutenberg plugin experiments. Other older books present templates only as PHP files with template tags, or describe the Site Editor only from the site owner’s point of view and never show the files behind it; both views still exist, but a block theme’s templates are the files described here.

Templates and parts are plain HTML files, not PHP. Anything that must be computed (the current year, a translated string, a list of posts) comes from a dynamic block that renders on the server, or from a pattern referenced with <!-- wp:pattern {"slug":"lumen/..."} /-->, whose PHP runs when the template is rendered.

The complete theme used on this page has this layout:

Source: Theme Handbook: Theme Structure

style.css (name, Version: 0.1.0, Requires at least: 6.9, Requires PHP: 7.4, Text Domain: lumen) and the colour palette and layout sizes in theme.json are the ones shown in Themes Overview; this page adds only the template keys of theme.json.

A template is a sequence of blocks serialized as HTML with comment delimiters, the same format the block editor stores in post_content:

The front end does not validate anything: do_blocks() renders static blocks' stored HTML as written. The editor does. When the Site Editor loads a template whose static HTML differs from what save() would produce, it marks that block as invalid and offers to attempt recovery or convert it to HTML. A template that looks right on the site can therefore be broken for the site owner. The reliable way to produce valid markup is to build the layout in the Site Editor and copy it from the Code editor (More options > Code editor), or export it (see Exporting edits back to files), then tidy the indentation.

Rules that keep templates portable:

Source: Block Editor Handbook: Markup representation of a block

A template part is an HTML file in parts/ inserted with the Template Part block. The lumen header holds the site title and a Navigation block; the footer holds a line of text and the tagline:

Source: Theme Handbook: Template Parts

Source: Theme Handbook: Template Parts

The leading <!-- parts/... --> comment is only a label on this page; the files start with the first block. A template inserts a part by slug with <!-- wp:template-part {"slug":"header","tagName":"header"} /-->.

The Template Part block’s attributes are slug (the file name without .html), tagName (header, footer, main, section, aside, article or div), area and theme. Without tagName, the element comes from the part’s area (area_tag below).

Each template below starts with the header part, wraps the page body in a Group rendered as <main>, and ends with the footer part. Which file serves which request is the template hierarchy’s job; in short, index.html is the final fallback, single.html and page.html serve posts and pages, archive-lp_book.html and single-lp_book.html are the post-type-specific versions for books (the lp_book type registers has_archive, so /books/ is its archive), search.html serves ?s= requests and 404.html serves requests that match nothing.

The Query Loop block (core/query) is how a template lists posts. Its children repeat or wrap the list: Post Template (core/post-template) repeats its inner blocks once per post, Pagination and its Previous, Numbers and Next blocks page through the results, and No Results renders only when the query is empty. Query Title shows "Books", "Search results for: …​" or an author name, depending on its type.

inherit: true is what makes one template serve many URLs: archive-lp_book.html lists books at /books/, index.html lists posts on the blog, and search.html lists results, without any of them naming a post type. With an inherited query the perPage attribute is not used; the page size comes from Settings > Reading ("Blog pages show at most", the posts_per_page option), and changing it changes the archive. To change the main query (for example, 12 books per page on /books/ only), hook pre_get_posts in a plugin rather than switching the template to a custom query, which would run a second query and break pagination. inherit: false, as in the "More from the catalogue" loop, is for secondary lists.

The post blocks render one field of the current post, inside a Post Template or in a single template:

A Post Terms block for a taxonomy that the post type does not use renders nothing; it does not fail. A block that depends on a post type supports value (featured image, excerpt, comments) also renders nothing when the type lacks that support, which is why lp_book registers excerpt and thumbnail.

Source: Block Editor Handbook: Core Blocks Reference

A custom template is a template that is not part of the hierarchy and that an editor chooses per post in the Template panel of the post editor. Older books call them "page templates" and create them with a Template Name: comment in a PHP file; block themes list them in customTemplates in theme.json (shown above), with the file in templates/. Each entry has name (file name without .html), title and optionally postTypes, which defaults to page only. Lumen ships two:

page-wide.html is page.html without the Post Title, with the main Group and the Post Content set to "align":"full" and the default (unconstrained) layout. The book template:

Source: Theme Handbook: Custom Templates

The choice is stored in the post’s _wp_page_template meta as the template slug (page-wide), the same meta that classic page templates use, and wp post update <id> --page_template=page-wide sets it from WP-CLI. A custom template whose name matches a hierarchy file (single, archive) would be confused with it, and a custom template missing from customTemplates still works but shows its slug as title and is offered for pages only.

A plugin that adds a post type usually wants it to look right in any block theme, not only in one built for it. Before WordPress 6.7 that meant filtering get_block_templates and pre_get_block_file_template. Since 6.7, register_block_template() registers a template with a name of the form plugin-slug//template-slug, and unregister_block_template() removes it. The lumen-catalog plugin registers a single book template, used when the active theme has none, and a custom "printable sheet" template offered for books:

Source: Make WordPress Core: New Plugin Template Registration API in WordPress 6.7

The markup lives in wp-content/plugins/lumen-catalog/templates/, so it can be edited and validated like a theme file. Its single-lp_book.html is a plain version of the theme’s (header part, Post Title, Post Featured Image, Post Terms for lp_genre, Post Content, footer part); book-print.html drops the header and footer:

Source: Code Reference: register_block_template()

How the registry behaves, as checked on 7.1.3:

Source: WordPress 7.1.3: class-wp-block-templates-registry.php

The examples run on the Compose stack of Local Development Environments (WordPress 7.1.3 with Apache on port 8080, MariaDB 11.8 and a wordpress:cli-2.12.0-php8.4 service named cli), with the theme and the plugin bind-mounted into both the wordpress and the cli services:

Source: Docker Hub: wordpress official image

Source: WP-CLI: wp theme activate

The resolved templates, their source and the plugin that also provides them, come from get_block_templates():

Source: Code Reference: get_block_templates()

Template IDs have the form theme//slug, even for plugin templates: lumen//book-print has source plugin, while lumen//single-lp_book comes from the theme file and only notes that lumen-catalog registers the same slug. Running the same script with Twenty Twenty-Five active lists twentytwentyfive//single-lp_book with source plugin.

The rendered pages show which template answered each URL (--resolve maps the host name without editing /etc/hosts):

Source: Theme Handbook: Template Hierarchy

Every page also starts with <header class="wp-block-template-part"> and ends with <footer class="wp-block-template-part">: the tagName of the Template Part blocks. The blog index has no <h1> because index.html has no Query Title. Assigning the custom templates changes the output of single URLs:

Source: WP-CLI: wp post update

After that, /about/ renders without a title (page-wide), and /books/the-lantern-keeper/ renders the plugin’s printable sheet: the title and "Series: The Tidewater Cycle" with no <header> element, because book-print has no header part.

The Site Editor never writes to the theme folder. When the site owner saves a template or a part, WordPress creates a post with the template’s markup, and from then on that post wins over the file:

Source: REST API Handbook: Templates

The REST API describes the result in each template’s fields: source is theme, plugin or custom (edited), origin says where a customized template came from, wp_id is the post ID, has_theme_file tells whether a file of that slug exists (and therefore whether "Reset" is possible, or only "Delete"), and is_custom marks custom templates. The endpoints are /wp/v2/templates/<theme>//<slug> and /wp/v2/template-parts/<theme>//<slug>.