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!

Restricting User Content: A Dialogue Among Themers

I had a Slack chat with my colleagues recently that we thought might be of interest to other themers.

Ernesto: I have a small theming question I’d like to clarify. Let’s say I have a page that is used as front page and there’s a section in the front page that displays some text. I can display the page’s content there, using the_content(), but I would only want there to be text — no fancy shortcodes or custom content, just basic formatting.

Would you create your own content filter for that section? Something like adding wpautop, convert_smileys, and wp_kses_post (possibly others too, if they make sense) into that filter? Or just use the_content() ?

I am leaning towards the filter approach, since it may give me what I want, without giving users full liberty to put all sorts of things into a div that is supposed to hold some minor text and content.

Tammie: This feels like a UX issue too. Why are you restricting?

Ernesto: Because it’s not a full content post, it’s a space where there should be one or two paragraphs at most. Just some introductory text.

theme screenshot

Tammie: Then why let full content appear anyway? Post restricting is expected behaviour, page restricting isn’t. Let’s not add a new behaviour.

I’d say the_content() and if user messes up, well…

If you limit that it’s adding a new behaviour.

Ernesto: Yeah, that makes sense.

Caroline: I’d agree with keeping it as simple as possible.

Tammie: Maybe they want to add a link. Adding a link there is a totally expected thing.

Caroline: So, the_content() works 🙂 And then with [the new content settings feature we’re working on] they could change it to the_excerpt() someday soon.


Tammie: Yep, win win.

Ernesto: Very good point… I see no problem with using the_content(), but since I know users want to add everything + the kitchen sink, I was just trying to avoid that.

Caroline: Hahaha.

Ernesto: So yeah, win win.

Tammie: Well that’s assuming they do. Many don’t.

Technically the ones that do make up for ones that don’t😉

David: Yeah, the_content() all the way.

Kathryn: Agreed 100%.

Ernesto: It’s interesting knowing your thoughts on this😀

David: If they put too much content in there, make the theme break elegantly.

Kathryn: If user wants to make their site busy, let them do it.

Kathryn: Users shouldn’t put a zillion widgets in one widget area, but we let them do that😉

Ernesto: Hehe, let them break and then tell them well… you shouldn’t do that.

David: It’s our job as developers to make themes that just work. Part of that is making edge cases not blow up a theme.

Tammie: Well, there’s hand holding and there is spoon feeding. Hands > spoons.

Kathryn: Very much agree re: “Part of that is making edge cases not blow up a theme.”

Also, making cluttered/ugly is different than “breaking”.

Ernesto: I think this is a very good & mature way of thinking… adding stuff for edge cases just makes the theme bloated.

Tammie: Also, edge cases aren’t always bad. We tend to have edge PTSD.

Kathryn: And there’s so much in between cluttered and minimal that is going to look just fine, I think.

Tammie: Yep.

Ernesto: Right, very good discussion and input, thank you so much, that’s why I love y’all:-)

Tammie: Also I kind of love the fact you didn’t even suggest a theme option for that.

Kathryn: Ha.

Ernesto: Hahaha.

Tammie: Times have changed and I like them.

Ernesto: I was going to admit it crossed my mind, but then noticed a page would be cleaner.

Tammie: And that’s why I have even more love about it. Self correcting rocks.

Ernesto: “If they put too much content in there, make the theme break elegantly.” – David Kennedy: Seriously?

David: Yep, I think that’s a sign of theme greatness.

Ernesto: That’s right, the I did what I could to hold the user’s content attitude, I like that too. Definitely adding some float-clearing there.

David: Before this, I worked at a place with a giant, talented editorial team. I thought, Perfect, we can work with them to get exactly the content we need! But they found ways to break things all the time. So whether you know the content, or don’t know it, make it highly fault tolerant.

Ernesto: Very very good advice, thank you!