Getting Started with Block Themes: Templates

Full Site Editing provides a new and exciting way to build themes, compared to how we created themes in the past. If you are new to this, there’s nothing to worry about, it’s simply a different way to create themes, leveraging the existing template hierarchy we all know and love.

List of templates under Appearance » Themes.

A block-based theme can be customized from the Site Editor by making use of templates and template parts. A template is analogous to a template file in WordPress, following the same naming convention from the template hierarchy. You can edit templates from the Site Editor, or in the Block Editor under Appearance » Templates.

A template can contain individual blocks, or it can use reusable structural template parts, such as header, footer, and sidebar, for example. Template parts are not limited to the common reusable areas of a site, they can be virtually anything: a contact form, a call to action banner, or anything you want it to be.

When you update a template part from within a template, the template part is automatically updated everywhere (on all templates that use it). This works in the same way as reusable blocks, streamlining the process of working with templates.

The complexity of your theme will determine how many templates you need to create. You have freedom to use the Site Editor in any way you like, but for most themes you’ll want to create some template parts. 

Templates live in the theme code, inside the block-templates/ directory, as individual HTML files. Template Parts are stored in the block-template-parts/ directory.  Both templates and template parts are automatically loaded when WordPress loads, and are readily available in the Site Editor and Block Editor.

Source code of a template HTML file.

Templates and template parts can be stored as data, just like posts or pages. You can save a template and design your site’s behavior directly from the Site Editor, without having to provide the template HTML file in the first place.

Block templates

In the classic way of theming, we usually have functions that give us the different parts that make up a post, such as the_title(), the_content(), and so on. Block themes give us the same features using blocks directly!

For this purpose, some blocks have been made to be used with block-based themes. For example, you’ll most likely use the Site Title block in your site’s header while your single post template will most likely include a Post Title and a Post Content block.

As we’re still early in the process, the number of blocks is relatively small, but more will be added as the project evolves. For more information on this, you can refer to the official block themes reference.

When you build your template there are some important blocks you’ll want to use, which are covered in the sections below.

Site Level blocks

These blocks will be the same on every page – they get their content from the database. If you change the Site Title in this block, it updates everywhere on the site:

  • Site Title
  • Site Tagline
  • Site Logo


Navigation is one of the most important parts of a website. The navigation block allows you to select menus you have previously created, or create new ones directly from the Site Editor.

If you have a header template part, this is a good place to add the Navigation block.

The navigation block in use.

Query block

The Query Block is different from other blocks; its content changes depending on the context in which it’s used. 

On the front page, the Query block will show your latest posts (by default). On an archive / category / tag page, the block will show the relevant content for that page. 

There are several blocks you can add inside the Query Block:

  • Post Title
  • Post Content
  • Post author
  • Post Comments
  • Post Comments Count
  • Post Comments Form
  • Post Date
  • Post Excerpt

You can combine these dynamic blocks with other blocks, for example columns, to change the layout of your posts and pages to your liking.

Dynamic blocks are blocks that use placeholders in the Site Editor, but will actually read information from the database when the blocks are rendered into the page. Therefore, it’s completely normal to not see the actual content when you are editing or inserting the block,  it will appear when the block is properly rendered.

Saving templates

After you have created all the templates and template parts in the Site Editor, you can save your templates to their corresponding HTML files. These can then be included in the theme.

Templates can be exported from the Site Editor, by clicking on the three dots button on the top-right hand side, and then clicking on Export.

Exporting a template from the Site Editor.

After exporting, you get a ZIP file downloaded to your computer, with all templates and template parts. You can extract the ZIP archive and copy the block-templates/ and block-template-parts/ directories into your theme and you’re good to go!

When the template files are bundled with the theme, they will automatically be loaded when WordPress starts. There is no need to import or create the templates, they are loaded directly!

Template loading order

As mentioned above, if a template is saved into the theme code, it will be automatically loaded on startup. You can make edits to the template from the Site Editor. 

Once the template is saved in the Site Editor, the template file will no longer be used. This means that changes saved from the Site Editor take precedence over the content stored in the template HTML files.

Have in mind, that if you make edits to any of the templates provided by the theme, the template you saved with your changes will be used instead of the template on disk. This means, if the theme ships an updated version of the template, you will not be able to see the changes unless you delete the templates from Appearance » Templates.

Up next, we’ll be talking about Global Styles, stay tuned!

Author: Ernesto Méndez

Theme Generator | Automattic