The introduction of Full-Site Editing in WordPress 5.9 was an even bigger shift than the addition of the Block Editor in 5.0.

Imagine using blocks to change the appearance of your homepage. Or adapt the header of your website. Or even create an entirely new template for single posts. All through the same interface you’ve been using to create your content.

With a feature as important as this, it pays off to start gathering experience as early as possible. That was the situation that I found myself in in 2020.

How this article evolved

I was eager to learn, and I decided to recreate the Bosco theme I released in 2014 as a full-site editing theme. Keeping the classic design intact, but changing all the technical foundations.

And I originally gathered the lessons I learned during this initial build in this article, titled “What I learned building a Full-Site Editing theme”. But I ended up removing the “a” after a few months.

As of 2024 I’m looking back on 6 years of block building expertise. That’s over 30 websites for clients large and small that run on block-based themes.

So rather than just focussing on one aspect of Full-Site Editing, this is a quick run-down of the key lessons learned during these projects.

Choosing a design to build

Back in 2020, full-site editing themes were still missing a lot of essential features. So it was important to choose a theme design that fits with these constraints.

Hence why most of the early Full-Site Editing compatible themes were single column blog themes. Hence why Bosco was a good choice for my first block theme project:

This led to a “all block themes look the same” message that was hard to shake. So a good think, building with early versions of the Site Editor, provided fodder for critics.

All these years later, despite many beautiful block-based designs out there, the same critics are still leveled at the Site Editor.

The Yoga fashion demo site of the Basti WooCommerce block theme.

That doesn’t mean that the tool (the Site Editor) doesn’t influence the designs that can be built.

But the question isn’t “what can be built”. But rather it is “what should we built”, and “how should we build it”.

This isn’t a technical limitation. No it’s one of time and money–essential for professionals building websites for clients.

In the old days, the approach was to create a design without any technical considerations. That is still possible, however it’s not optimal. You risk having to spent time on little design features that all in all don’t offer a lot of return on investment.

But beyond that the challenge of building a block theme is not to create mockups. It is to create a design system.

Meaning that the designer needs to put select a cohesive set of colors, typefaces, font sizes, spacing sizes,… that are used across all pages of the website.

Building themes using the Site Editor

Unfortunately a lot of emphasis is given onto small demonstration builds. The I rebuilt TechCrunch.com in 30 mins with WordPress video is a good example of this. The creator, Jamie Marsland or Pootlepress, is sponsored by WordPress.com.

This gives a lot of visibility to this and similar videos. While this are a cool demonstration of how powerful the Site Editor is, it’s a poor representation of how professionals build websites.

You are not supposed to have to click a gazillion buttons, or manually enter values for fonts and colors. Because that is not only a lot of unnecessary work, it also means that you won’t be able to change the design and have these changes applied across all templates.

The Site Editor offers you a similar development workflow as you are used from classic themes. You can still have great HTML markup. And you can still reuse styles across block.

It’s just that the tools to do this have changed.

Is block theme development no code?

Working on the navigation in the site editor.

Back in 2020, when I created the first block theme version of Bosco, I still spent a lot of my time in the code editor.

Whether you needed to add anything to the theme.json file, add a new blank template, or create a pattern. For all these tasks you needed to go back to the code editor.

Now this isn’t the case anymore.

I now rarely find myself going back to the code editor. Beyond the initial setup of the colors, typography, and spacing settings. And sometimes adding a bit of CSS.

The tooling is improving, and in the near future developers will rely only on the Site Editor and a few helper plugins.

Using a visual builder is the new workflow that we need to get used to for creating themes.

Creating Templates and Template Parts

The list view shows the structure of the blocks used in the template.

At a certain point, you will have created enough of a template in the site editor that you are ready to add it to your theme. All you need to do is export the design through the site editor.

This will give you designs, which will give you a set of HTML files in two directories: templates and parts. It’s these files that are used to render the frontend. They are also used as a starting point when entering the site editor. That is if there’s no user-defined template.

Full-site editing distinguishes between two types of templates and template parts. Theme-provided templates are HTML files, and they are placed in the theme directory in wp-content/themes. User-provided templates are custom post types (wp_template and wp_template_part), which are stored in the database.

For example if the theme provides an index.html file, and the site has a wp_template post with the name of index, the post content will be used to render the frontend. But if the theme as an archive.html template, and there is no archive post, then the HTML file from the theme will be used.

While this is great for customizing a site as a user, it’s not the greatest experience for a developer. Because when you first create your theme in the site editor, you will save the templates and template parts to the database. Then you export them as HTML files, and add them to your theme. Once that is done you need to delete all the existent full-site editing posts, so that the theme-provided templates are used.

This is where the developer experience currently falls apart. Because as you continue to make refinements to your templates, these changes are not synchronized to the theme. You either need to re-export the templates each time, or to copy the changes from the post content in the database.

A New Way Of Implementing Designs

When looking at a design, developers naturally divide it up into boxes–in your head you’re thinking “okay, this goes here, and that goes there”. Using that roadmap you put together the templates. What for outsiders looks like a tangled mess of HTML tags and PHP code all makes sense to a theme developer. But when it comes to creating full-site editing themes, you need to completely rework your processes.

Let’s look at the header implementation as an example:

This is the code from the Bosco theme:

<header id="masthead" class="site-header" role="banner">
	<div class="site-branding">
		<h1 class="site-title">
		    <a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
        </h1>
		<h2 class="site-description"><?php bloginfo( 'description' ); ?></h2>
	</div>

	<nav id="site-navigation" class="main-navigation" role="navigation">
		<button class="menu-toggle"><?php _e( 'Menu', 'bosco' ); ?></button>
		<?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?>
	</nav>
</header>

Getting the site title and site description is easy enough: there are blocks for that. But how do I get a header tag in full site editing?

To find that answer, we need to change the question we’re asking. From “how can I create this tag?” to “why do I need this tag?” A header tag is a container: it groups elements together, and offers the opportunity to add ids and classes for styling. In block-based themes, the Group block provides the same capabilities.

So the first implementation looked like this (in pseudo-code):

Site Header (Group <header>)
    Site Branding (Group <div>)
       Site Title block (<h1>)
       Site Description block (<p>)
    Site Navigation (Group <div>)
       Navigation block

Once I build this out, I moved this part of the design to a template part. Template parts are added through a block as well, and can accept a tag name. That allowed me to get rid of the first group block. But as I went through and adapted the CSS, it appeared to me that the other two groups aren’t used either.

So I moved to this implementation:

Template Part .site-header
    Site Title
    Site Description
    Navigation .main-navigation

Building With Flexibility In Mind

The Bosco theme always displayed a navigation menu. If users didn’t select a menu, WordPress fell back to wp_page_menu(), and with that an autogenerated menu made up of all pages on the site.

But for the full-site editing version of Bosco, such an imposed choice is not a possibility. Because users can choose to not use a menu, or place the Navigation block outside of the header.

A variant of the Block-Based Bosco theme with the navigation menu placed outside of the header template part.

Another variant which uses no navigation menu placed at the top of the site.

In addition to this, the Navigation block also supports a vertical display. So I had to ensure that the styles I wrote were as flexible as possible, so that they could adapt to all these use cases.

So the final version uses the following structure:

Template Part .site-header
    Site Title
    Site Description

Navigation

The extra Group blocks where removed, the navigation was placed outside of the header template part, and the styles were adapted so that there’s no need for a .main-navigation class.

But developers will not only have to adapt to how users can use the new full-site editing blocks. There’s also a new approach to handling site-wide styles.

Consistent designs with Global Settings and Styles

As the term indicates, Global Styles are a way to define styling related properties for a theme. This ranges from the very general, like fonts and colors used throughout the theme, to the styles of specific blocks.

From an implementation standpoint, global styles are nothing more than a JSON file, named theme.json. But this single file replaces a lot of code in different parts of a theme’s code base. Because the appearance of current themes are handled through CSS, add_theme_support() calls, and various hacks.

Global styles centralize all these configurations in a single place. By defining font and color choices globally, customization options that are available to users fit well with the rest of the theme. At the same time, theme designers can opt out of these features, down to the level of individual blocks.

Some of the settings in the global styles are added to the page as CSS variables. By reusing these variables through the stylesheet, theme developers can ensure a consistent experience. Not only for the default appearance of a theme, but also when users choose things like custom colors or font sizes.

But as powerful as global styles are as a feature, they’re currently also very frustrating to deal with. Writing out JSON by hand in a file that quickly grows to 200+ lines and different levels of indentation is not easy. Especially because there is no validation, and small mistakes can break the entire file. This, coupled with the lack of documentation, makes it hard to find out where you made mistakes.

A Great End User Experience

With classic themes, the experience of customizing WordPress themes is sub optimal at best. Between settings screens, Customizer extensions, or even worse shortcodes, there is no consistent user-friendly way to change the appearance of a theme.

There are a lot of page builders in the WordPress ecosystem, which try to solve this issue. But the flexibility of a page builder is its biggest strength, and its biggest weakness. In addition the logic is based per page, and not per template type.

Full-site editing is less powerful then a page builder, but that also makes it easier for users to change templates. The global styles and the limited settings per block act as guardrails. This way users can focus on the most important customization options, without getting lost in a sea of possibilities.

A stable platform for developers

When I published to original version of this article, I had the following criticisms:

Big gaps in user and developer experience.
Constant changes to block markup breaking theme CSS styles.
New features are added in small bits and pieces.
Features were difficult to use, especially having to write styles in theme.json.

All of these are no longer valid. Despite constant criticisms on Twitter and elsewhere, block themes and the Site Editor are a stable and fully-evolved features.

Full-site editing themes are not just a blank canvas for users to build upon, but instead opinionated, beautiful designs that can be slightly adapted. Because the reason why page builders haven’t yet taken over WordPress themes completely is that not all users want to build out designs piece by piece.

In addition for theme designers, plugin developers, as well as freelancers and agencies it’s risky to tie your fortune to third party software. So far WordPress has always supported core features as long as possible–the Classic Editor being the notable exception. This makes using the site editor in WordPress a safer bet over a page builder by a commercial entity.

And finally full-site editing uses much of the same technical foundations as the block editor does. So if you have experience customizing blocks and tweaking themes for the block editor, you’ll feel right at home. The same goes for plugin developers: if you currently offer custom blocks for posts, you’ll be able to adapt these for the site editor.

How to go from classic to block themes?

In the very early days of Full-Site Editing, there was this idea that it would be possible to somehow “migrate” classic to block themes.

All these years later, this migration path has not materialized. And it never will.

The reality is that there is no automated way to migrate a classic theme to a block theme. Instead you have to rebuild from scratch. The same applies to any of the myriad of page builders out there.

Now many freelancers and agencies are reluctant to just go from building classic themes one day, to full on block themes the next.

What has also become clear is that there is no gradual adoption o

Currently there is no plan for gradual adaption of block-based templates by existing themes. Technically this would absolutely be possible. But I’m not sure that changing the foundations of an existing theme is worth it compared to releasing a new block version of the same design–as I did with Bosco.

I know that this is going to be difficult for a lot of theme developers, especially for those relying on market places. Once a theme has traction its very hard to justify putting resources into another theme. In addition users do not want to change a site that is looking and working exactly as they want it.

I do consider though that due to the ever changing nature of web design trends, themes don’t remain popular forever. Theme shops need to release new designs, and by choosing full-site editing for these, adoption will happen naturally over time.

Table of Contents