Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 68 ยท Block Themes and the Site Editor

Block Templates and Template Parts

Learn how block theme templates and template parts work - HTML files with block comments, post content, the Query Loop block, custom templates and Site Editor versus files.

In a classic theme, single.php is a script: it calls get_header(), runs the Loop and calls get_footer(). In a block theme the same job is done by a file named templates/single.html. It contains no PHP at all, only a tree of blocks written as HTML comments. WordPress reads that tree, turns each block into HTML (some blocks, such as the post title, are rendered by PHP behind the scenes) and sends the page.

Two kinds of files carry the layout. Templates describe a whole page type: a single post, an archive, a 404 page. Template parts are reusable regions that templates include, usually the header and the footer. This lesson shows how both are written, how WordPress picks a template, how the Query Loop block replaces the PHP Loop, and how editing in the Site Editor relates to the files in your theme. The theme files are read-only here, and a plain-PHP stand-in renders a template tree to HTML so you can see the idea working.

You should know the basics from Block Themes: The Big Picture and the template hierarchy.

A template is a tree of blocks

Here is a complete templates/single.html:

HTML
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-featured-image /-->
  <!-- wp:post-content /-->
  <!-- wp:post-terms {"term":"category"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

The important blocks:

  • wp:template-part includes parts/{slug}.html. The tagName attribute chooses the wrapper element (header, footer, aside, and so on).
  • wp:post-title prints the title of the current post, as a heading of the chosen level (default 2). With "isLink":true it links to the post.
  • wp:post-content prints the content of the current post or page. A template without it would show no article text.
  • wp:group is a container; it can become a main, section or div and controls layout (constrained, flex, grid).
  • Self-closing blocks (... /-->) are rendered entirely by PHP, so their markup in the file is just the comment.

Static blocks, such as a Group, keep their HTML inside the file (the <main class="wp-block-group"> line). That stored HTML must match what the block would generate, or the editor shows a "block validation" warning. The easiest way to avoid mistakes is to build the template in the Site Editor and copy its markup from the code editor view (Ctrl+Shift+Alt+M).

Template parts

A template part is just a file in parts/:

HTML
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Save it as parts/header.html and any template can include it with <!-- wp:template-part {"slug":"header"} /-->. Change the file once and every template changes.

In theme.json you can describe parts to give them a friendly name and an area. Areas (header, footer, uncategorized) tell the Site Editor where to list the part and which parts it can offer when a user replaces one:

JSON
{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" },
    { "name": "sidebar", "title": "Sidebar", "area": "uncategorized" }
  ]
}

Parts can include other parts, and you can use the same part in many templates, which is why a clean split (header, footer, post meta, sidebar) pays off.

Which template is used

Block themes use the same decision logic as classic themes, with .html instead of .php. For a single book (custom post type book, slug dune) WordPress looks for these files, most specific first:

flowchart TD
    A["single-book-dune.html"] -->|"missing"| B["single-book.html"]
    B -->|"missing"| C["single.html"]
    C -->|"missing"| D["singular.html"]
    D -->|"missing"| E["index.html"]

The first existing file wins; index.html is the last resort, which is why every block theme needs it.

Other common names: page.html and page-{slug}.html, archive.html and archive-{post_type}.html, category.html, taxonomy-{taxonomy}.html, author.html, search.html, 404.html, home.html (the blog posts page) and front-page.html (the site front page).

Custom templates

A page can also be assigned a template chosen by the editor. Register one in theme.json, then create the file:

JSON
{
  "customTemplates": [
    { "name": "landing", "title": "Landing Page", "postTypes": ["page"] }
  ]
}
TEXT
templates/landing.html

Now editors see "Landing Page" in the template picker of every page. Custom templates are the block-theme replacement for the classic "Template Name:" header comment.

The Query Loop replaces the PHP Loop

Archives, the blog page and "latest posts" sections use the Query Loop block (wp:query). It holds the query settings and contains inner blocks that render once per post.

HTML
<!-- wp:query {"queryId":0,"query":{"perPage":10,"postType":"post","inherit":true}} -->
<div class="wp-block-query">
  <!-- wp:post-template -->
    <!-- wp:post-title {"isLink":true} /-->
    <!-- wp:post-excerpt /-->
  <!-- /wp:post-template -->

  <!-- wp:query-pagination -->
    <!-- wp:query-pagination-previous /-->
    <!-- wp:query-pagination-numbers /-->
    <!-- wp:query-pagination-next /-->
  <!-- /wp:query-pagination -->

  <!-- wp:query-no-results -->
    <!-- wp:paragraph --><p>No posts found.</p><!-- /wp:paragraph -->
  <!-- /wp:query-no-results -->
</div>
<!-- /wp:query -->
  • inherit: true means "use the main query of this page", so on a category archive the loop shows that category's posts and WordPress handles pagination. Set it to false to run your own query using postType, perPage, taxQuery and other fields, for example "three latest books" on the home page.
  • wp:post-template is the block whose inner blocks repeat for each post. It is the visual counterpart of while ( have_posts() ) { the_post(); ... }, and it supports list or grid layouts.
  • wp:query-no-results is shown when the query returns nothing, like the else branch of the classic Loop.

Under the hood, the Query Loop block builds a WP_Query, so everything from WP_Query in Depth still applies.

Rendering a template tree

The stand-in below renders a template the way WordPress does it, in miniature: parse the block comments, replace dynamic blocks with generated HTML, load template parts from a registry and repeat the Post Template block once per post. The real renderer is render_block() and the block render callbacks; this is only a model of the data flow.

PHP Rendering a block template to HTML

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The two outputs come from the same header and footer parts, which is the benefit of parts. The index template shows only two posts because the query block asks for perPage: 2. Static blocks (the Group and its <main>) print the HTML stored in the file, whereas dynamic blocks generate their markup at render time.

Editing in the Site Editor versus editing files

You can change templates in two ways, and it matters which one you use:

  • Files in your theme. You edit templates/single.html in your code editor. This is the version-controlled source of truth and what you ship to every site that installs the theme.
  • The Site Editor (Appearance > Editor). A site owner edits visually, and WordPress saves the result as a wp_template or wp_template_part post in the database. That copy takes precedence over your file on that site.

After a template has been customized in the database, changes to your theme file do not show on that site until the customization is cleared (the Site Editor offers "Clear customizations", and deleting the saved template does the same). Developers normally design in the Site Editor on a development site and then export the result back to files, either with the Site Editor's export tool (a zip of the theme) or with the official Create Block Theme plugin, and commit those files. Do not hand-edit stored templates in the database.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which block prints the main text of the current post or page inside a template?

    wp:post-content renders the content of the current post or page. A single or page template without it would not show the article body.
  2. 2. You create parts/sidebar.html. How do you use it in a template?

    Templates include a part with the Template Part block and the part's file name as slug. There is no PHP in block templates.
  3. 3. A single book has no single-book.html or single.html in the theme. What does WordPress try next, in order, before giving up?

    The single-post chain ends with singular.html and then index.html, the fallback that every block theme must have.
  4. 4. A client edited the header in the Site Editor. You now change parts/header.html in the theme and deploy, but the site looks unchanged. Why?

    Site Editor changes are stored as wp_template_part posts, and those take precedence over the file. Clear the customization to use the file again.
  5. 5. What does inherit set to true do in a Query Loop block?

    With inherit true the block displays the results of the main query for the current URL, so archives, categories and search pages work without extra settings.

Summary

  • Block templates (templates/*.html) and template parts (parts/*.html) are trees of blocks written as HTML comments, without PHP.
  • wp:template-part, wp:post-title, wp:post-content and wp:group are the building blocks of most templates.
  • WordPress uses the usual template hierarchy with .html files, ending at the required index.html; custom templates are registered under customTemplates in theme.json.
  • The Query Loop (wp:query with wp:post-template) replaces the PHP Loop and can inherit the main query.
  • Site Editor edits live in the database and override theme files until cleared, so export finished designs back into files.

Next, build reusable sections for editors: Block Patterns.