Creating a Block-based Theme Using Block Templates

This post outlines the steps I took to create a block-based theme version of Twenty Twenty. Thanks to Kjell Reigstad for helping develop the theme and write this post.

There’s been a lot of conversation around how theme development changes as Full Site Editing using Gutenberg becomes a reality. Block templates are an experimental feature of Gutenberg (as of 7.2.0), and using them to create block-based themes is in exploratory stages of development. 

A block-based theme is a WordPress theme with templates entirely composed of blocks so that in addition to the post content of the different post types (pages, posts, …), the block editor can also be used to edit all areas of the site: headers, footers, sidebars, etc.

Gutenberg Handbook

Before diving in, I’ll reiterate that much of how this works is subject to change. This spec is in a very early stage. I hope by writing this, your interest is piqued to learn more and contribute your own experiment to the WordPress theme experiments repository.

Step 1: Create the theme project

In its simplest state, a block based-theme’s structure should look something like this:

theme
|__ block-templates
    |__ index.html
|__ block-template-parts
    |__ header.html
    |__ footer.html
|__ functions.php
|__ index.php
|__ style.css

This is refreshingly simpler than most WordPress theme boilerplates. Here’s a quick overview what each file and directory does:

• block-templates/: page templates that are composed of blocks. These follow the same template hierarchy as traditional themes.
  • index.html: the primary / fallback template to generate a post or page. (Analogous to index.php in traditional theme templates.)
• block-template-parts/: the common collections of blocks to be used in block templates.
  • header.html: The global header, expressed in Gutenberg-generated HTML.
  • footer.html: The global footer, expressed in Gutenberg-generated HTML.
• functions.php: This contains the usual theme setup and any other reusable functions.
• index.php: This is actually just an empty file. You can technically remove it, but it’s a good habit to include an index file in every directory.
• style.css: Contains your theme’s styles as usual.

Recreating Twenty Twenty as a block-based theme required adding a few extra stylesheets. Overall, I chose to add no extra page templates to keep the demo as understandable as possible.

Step 2: Create the block templates + block template parts

There were just two that needed to be totally rebuilt as blocks: the header and footer. The process for turning these areas into block templates was something along the lines of:

1. Attempt to create the template parts in the block editor
   • This can be done in a draft post or page. If you’ve enabled the Full Site Editing experiment in the Gutenberg plugin, you’ll see a new admin panel area Appearance/Template Parts — an area where in the future I could create, store, and edit the block template parts in my theme.
2. Style them as closely as possible using the editor
3. Add block style variations + additional theme CSS to address any gaps that the core editor
   • Most of these styles were already present somewhere in the Twenty Twenty theme CSS, so I just needed to make minor modifications to assign them to the new blocks.

Step 3: Save those block templates + template parts as distinct files

When Full Site Editing is enabled via the Gutenberg > Experiments panel, Gutenberg will expect that your theme provides block templates, overriding the normal templating behavior:

Once I had my template parts designed and displaying properly, I would switch over to the Code Editor view, copy the markup generated, and paste the code into its respective file within my theme directory’s block-template-parts folder.

Edit: there’s an easier way to do this without switching to the code editor. You can select all blocks (Meta+A), copy (Meta+C), and paste into your text editor.

Step 4: Add theme starter content

In order for the theme to be populated with pages and content, I borrowed the official TwentyTwenty theme starter content. This step wasn’t 100% necessary, but a nice addition to have some content when someone activates the theme on a fresh WordPress site.

Demo

Here is the result: a site running the block-based Twenty Twenty.

Potential Block Improvements

Converting the header and footer to blocks helped me identify some functionality that would be nice to add to core blocks. Some of these are already in the works.

• Navigation block
  • Control over how the menu is laid out and collapses in different viewports (#16829)
• Columns Block
  • The ability control the padding and margins (#10730, #16660)
  • Adjusting the size of one column, the remaining columns don’t resize equally (#19515)

How is this better than what we have now?

The structural block-based theme changes are generally not obvious on the front end. The process of switching between the Code editor, a template file, and previewing the site to achieve the intended design was tedious. However, this is just an interim step before we’re hopefully able to create and edit our theme (and your entire site) via Gutenberg.

The end benefit will become most apparent when the user can edit every piece of the page individually using Gutenberg. Being able to compose, manage, and reuse parts of your theme all within one visual interface is an exciting idea and one that’s close to reality.

The other exciting aspect of this process was that it required very little PHP — just a few block style variation declarations and standard theme support registration. Everything else is CSS and HTML generated by the editor. To me this feels like a step in the right direction, lowering the barriers to entry for folks that are new to theme development and WordPress.

I invite you to try it out; your comments and feedback are more than welcome. The source code for this theme is available on GitHub:

https://github.com/WordPress/theme-experiments/tree/master/twentytwenty-blocks

In that repository, you’ll find a handful of other block-based theme experiments: converted versions of Twenty Nineteen, the Gutenberg Starter Theme, and a theme called Parisienne. Each contains instructions for installation and activation.

By the way, the theme-experiments repository is open for PRs! I’d love to see more people creating and testing themes that use this method: that’s the only way it’ll grow and improve.

Feel free to ask questions in the comments or in the repository, and thanks for reading!