If This Is Modern WordPress Theme Development, Sign Me Up

I have had a block theme idea rattling around in my brain for a while. For months, I have considered building a single-page profile/card theme, and I finally sat down and put in the work over the weekend. In part, I just wanted to do this for fun. However, another part of me wanted to see how block theming has progressed from a developer perspective.

Inspiration for this theme came from a few other people and projects. Kjell Reigstad’s two-column landing page experiment from October 2020 first triggered it. A recent question to the Ask the Bartender column about compact-and-cozy themes got my creative juices flowing again. However, seeing the Themes Team approve a similar block theme, Miniblock OOAK, by Carolina Nymark meant that the rules were now lax enough to possibly put something like this out into the world.

One of the problems is that block-based theming has burned me before. I spent months building a new project last year in my precious free time only to have Gutenberg plugin updates wipe out my progress weeks later. I knew things could change with the unstable foundation of alpha-level software, but it was still deflating. Needless to say, I could never find the motivation to pick it back up.

With WordPress 5.9 and a more stable block-theming system just mere days ahead, it was time to give it another shot.

I wanted to learn block theming deeply. The only way I could do that was to go back to the beginning. I needed to reacquaint myself with those foundational elements of plain ol’ HTML, CSS, and PHP. And forget everything I thought I knew building on top of the modern web. I needed to become a noob again.

Technically, it is impossible to forget everything I know without incurring some sort of amnesia. However, maybe — just maybe — I could get back to the building blocks of the web.

Could I spin up a WordPress theme without a complex web of dependencies spanning over 900 projects in my /node_modules folder?

Could I create something without dutifully pulling in my base PHP scripts via Composer?

Could I, you know, just build a WordPress theme?

The first step was to check my ego at the door. When I set aside years of modern tooling and a workflow built around them, what I found was a beautifully-simple theming system that pays homage to WordPress’s roots but is flexible enough to extend for advanced builds.

This is not to say that there were no hiccups along the way, but we hear about those enough. Plus, I consider programming/development to be the art of solving problems.

I had a restless weekend. I got four, maybe five, hours of solid sleep between Friday and Saturday night. Perhaps I had so many projects and things going on that my mind could not shut them out. Regardless, I was back awake at 3:30am on Sunday morning, tired but unable to catch those much-needed Z’s. So, I cracked open my code editor and created a new theme project.

Within an hour, it was working. It was in decent enough shape to share with friends over Twitter in two.

The following is a screenshot of the current homepage. Technically, it is the only page. I have tinkered a bit since I pushed my first commits live.

Single box in the middle of a webpage.  The background has a light to dark blue gradient.  The box has an image of a mountain reflecting on a lake along with demo profile info.
One-page profile card theme.

This is a block pattern named “Reflections.” The mountain reflecting on the lake photo is from WordPress Photos and shot by Anne McCarthy. The gradient used for the background is a reflection of the image’s colors too, which I thought was a nice touch.

The theme includes several other patterns. The goal is to allow users to pick their favorite for their profile card, customize the content, and save. Easy peasy. I hit a snag with this, which I dive into at the end of the post. For the most part, everything went well.

What I Learned from the Experience

Creating WordPress themes with blocks is easy. Most things are structured and play by a standard set of rules. Templates go here. Parts go there. Plug in your settings over yonder. We are likely to see even more structure in future WordPress versions.

I built the theme from scratch using only my code editor and a local WordPress install. No Node modules. No PHP libraries. No build setup whatsoever.

I will likely use those things before this project is complete. Some tools simply make development easier. However, not needing them or diving into more complex PHP APIs has lowered the barrier to entry.

It felt like I had been transported back to the mid-2000s, just with a better system in place to take care of all the complex bits. For once, I could almost entirely focus on the design.

There are issues aplenty with the underlying system. Oddities like extra wrapper elements around wide-aligned blocks still exist in the editor. And, several blocks need updating — I am looking at you File block for not reusing the existing Button block.

Basically, there are quirks. As a themer, you learn to work with them in mind, wait for a fix upstream, or risk your sanity trying to find workarounds.

I am hesitant about sharing unfinished work, but I should also show proof. Those interested can check out the GitHub repo at the date of this article, at least before I do anything too crazy with it.

Some theme authors may look at my project and think it is too simple of an example. However, I could easily apply everything about it to a full-blown theme. The standards are the same, regardless of the size.

Maybe we should start rethinking what a theme is. With block-based theming being so young, we should all be doing a bit of experimentation.

A Missed Opportunity

I will get slightly technical in this bit because it is crucial for explaining a missed opportunity for a well-rounded user experience. The site editor is in a place where it is easy to build for more advanced users. Patterns help bridge the gap for those less technical, but they are not enough.

Think about the major sections of a webpage. Pieces like the header, footer, sidebar, content, and even sub-sections of those. As a user, how do you replace the entire content area design that is already on the screen with a different content pattern?

You could delete the one that is there and insert a new pattern. However, deleting and inserting sections of a page is a high-risk action.

If the area you want to change is a template part, you can replace one with another. That is assuming the theme author has registered any for that area. This is a low-risk action and one of the best features of the site editor.

For example, here are header templates that Twenty Twenty-Two registers as they appear under the “Replace” toolbar menu item:

Site editor open with the header template selected.  Under the "Replace" dropdown, there are two alternate header designs.
Replacing header template part in Twenty Twenty-Two.

However, that is not the theme’s entire array of header patterns — it has 18 in total. I imagine that most end-users will never discover them.

One of the downsides of creating patterns meant for specific template parts is that end-users have no way of replacing or transforming a part wholesale with a new pattern.

Theme authors can duplicate their efforts by copying the pattern code into the template part, assuming it has no PHP mixed in. Or, they can create those parts and pull in the associated pattern via the Pattern block:

<!-- wp:pattern { "slug":"namespace/slug" } -->

The issue with this approach is that the site editor does not display the pattern content in the “Replace” dropdown (did I just discover a bug?):

Site editor open with the content template selected.  Under the "Replace" dropdown, there are five alternate templates but their previews are not shown.
Template parts that use the Pattern block.

The solution should be simple. Patterns registered for a template part should be interchangeable via the UI. Or, parts that use the Pattern block should display correctly in the “Replace” dropdown.

22 responses to “If This Is Modern WordPress Theme Development, Sign Me Up”

  1. It is very easy to do. It’s not perfect, and there are missing pieces. But, it is really super easy once you understand the basics.

    The problem isn’t making one, it’s making one that has enough complexity and configuration capability where you feel it’s okay to give to other people.

    Basically, you feel like it’s simple enough that you can keep it to yourself and handcraft it as needed. Which is good, but also does raise the question “what is a theme?” indeed.

  2. Beautiful theme. Hey, check out the new Ghost theme (still in dvlpmt at GitHub), that will inspire you also.

  3. For starters, SO stoked to see one of my images used like this. Thanks for choosing it.

    Patterns registered for a template part should be interchangeable via the UI. Or, parts that use the Pattern block should display correctly in the “Replace” dropdown.

    There’s lots of issues open around “displaying contextual patterns”, including this one: https://github.com/WordPress/gutenberg/issues/28739

    What you’re describing feels like it falls into this work. Essentially, you want to see patterns more prominently displayed when folks are working with templates and template parts. At the risk of overwhelming with issues, I’ll point out the following two and leave it there:

    https://github.com/WordPress/gutenberg/issues/28737
    https://github.com/WordPress/gutenberg/issues/27575

    The long and short is that this work is underway to better display patterns both when starting blank and when actually editing current content so you can see at a glance what other options might fit nicely exactly where you’re editing. There’s obviously a substantial amount of work to get there :)

    Can’t wait to see your theme out there (along with Otto!). Ship away — it’s paving the way ultimately and I’d love to see a diverse take on block themes.

    • As always, thank you for digging up tickets for problems I’m having. :) There’s some really interesting ideas there that would would be ideal for this scenario.

      I will definitely ship the theme after cleaning it up and running it through the testing phase.

      • Great to see the X3P0 Reflections theme land in the org repo.

        This and the Miniblock OOAK theme make a nice change from the usual run-of-the-mill themes, and are quite inpsirational to me personally.

        Thank you for releasing the theme Justin and making it available to a wider audience.

  4. Concerning this new way of doing themes, what are the chances of still having themes (and plugins!) locked-in? … I’m tired of theme lock-in headaches. When do we definitively have the front-end interface apart from functionality?

    • Content and functionality are 100% separate from the design aspect when it comes to block themes. This is assuming your theme isn’t adding things like custom blocks, which is not allowed at WordPress.org anyway.

      The one thing that may be considered “lock-in” is making liberal use of a theme’s custom colors, fonts, etc. Because there is no standard naming convention for these under the hood, you could lose the styling on some pages when switching themes. But, your content and functionality do not disappear.

  5. This gives me a lot of hope. A lot. For the first time in a long time I’m excited about building new WordPress stuff.

  6. In another recent topic I suggested to learn JS deeply, but that turned out to be a wrong assumption. Still.. block themes are something else compared to classic themes. For me, a hobbyist classic theme developer, this is the right moment to retire 😏

    • I actually see block theming being a return to classic theming’s roots in many ways. This feels more like the “classic” that I remember from WP’s earlier days than the complexity that has been added in recent years.

      The big difference is really in the templating. Instead of HTML sprinkled with PHP tags, you have HTML with block comments.

      As far as theme.json goes, you can opt into as much or as little of that as you want. This is particularly true of the styling aspect. You can go full-on configuring everything in theme.json or stick with style.css.

  7. Could you talk more about how you’ve put this together, what is the process? Do you use a reference or build things up in the editor and export?

    I’m missing the process between the article and the end result on github, both of which are impressive. Thanks.

    • I generally try to keep the posts readable for a more general audience here, but I am always happy to discuss the technical details further. Feel free to ask me any question about the process.

      For this theme, I started with the theme.json file and filled out some of the settings that I knew I would want enabled/disabled. Carolina Nymark’s lesson on creating this file is a great starting point.

      From there, I added a templates/index.html template with a Post Content block just to keep things simple.

      <!-- wp:post-content /-->

      Since I knew it was just going to be a one-page theme with specific patterns, I could build those patterns out in the editor. All I needed was that block in the file to kick-off the process.

      Then, I headed over to the editor and designed the first profile-card pattern. Once I liked it, I created a pattern category via register_block_pattern_category() and pattern via register_block_pattern(). I repeated this same process for more patterns.

      Once I had my initial pattern in place, I also adjusted my template to display it instead of post content:

      <!-- wp:pattern { "slug":"namespace/slug" } -->

      As I continued building the theme, I made adjustments to the styles key under theme.json. Anything I could add there, went into that file. If I had other style adjustments not possible with it, they went into my style.css.

      That is how I got from Point A to Point B.

      I have since changed things a bit, cleaned up the code, and made things more to my liking. I’ve also added features like per-block styles (these get inlined automatically). I’ve added a few custom block styles and such. But, the primary process is the above.

  8. Thank you for sharing the theme Justin.

    It’s very interesting to see what you have accomplished with just the one template and one part.

  9. So the world of theming for WordPress now is a stack of config files with little control over actual markup?

    I have tried using gutenberg for client sites. But my clients has this habit of having me the designer actually design the website. They don’t want to mess around with colors, fonts, layouts etc. They want to input content into a form, and having it placed in a design.

    I feel like gutenberg and WP is tying their hardes to become a design tool, programming tool and CMS all in one.

    • So the world of theming for WordPress now is a stack of config files with little control over actual markup?

      Block themes are made up of standardized components (the blocks themselves) and markup. As the developer, you can take 100% control over the arrangement of these components.

      There is a single config file, theme.json, that allows you to opt into pieces of the global settings and styles features. You can use as much or as little of that as you want.

      I have tried using Gutenberg for client sites. But my clients has this habit of having me the designer actually design the website. They don’t want to mess around with colors, fonts, layouts etc. They want to input content into a form, and having it placed in a design.

      You can still design the website and have your clients only touch content. If anything, you could have even greater control over what those client content forms look like and where they are placed with the locking features in the block editor.

      • Would love to read more about how to do this. Because the way I always build sites for clients is create different custom post types, different custom fields, custom taxonomies, create different templates for the different sections/pages of the websites and in those templates I’m free to program everything I want in PHP.

        For example a client website would have ‘Projects’ which each have a relationship with ‘Publications’, both Projects and Publications would use ‘Authors’ or ‘Contacts’ (also custom post types with custom fields). All custom post types with many custom fields for all sort of meta data. And all could have custom taxonomies (project and publication categories), which link them together. So that when viewing a Projects page on the website it would show some list or grid or map of projects, maybe filterable with some filters (which I can easily build in PHP), each project also showing related publications (related with the shared taxonomy) and showing the authors. Etc etc.

        Clients would just go in WordPress and add or edit the custom post types Projects, publications, Authors (besides the normal Posts and Pages), fill in the form fields, click the taxonomy items, all relatively easy and pretty robust against clients messing anything up.

        I have read a lot about Gutenberg but I just don’t see how I can build this from creating a few blocks and patterns in the Gutenberg editor.

        • This sounds very similar to my development experience. I use custom post types to intentionally lock down the desired layouts for different sections of the site.

          Perhaps I’m missing the point and the new way of doing things is really aimed at people who want to build sites without designer and developer involvement but I feel like I spend a good chunk of my time turning off new features so my clients can just use sites without worrying about messing things up.

  10. As a previous Squarespace user and designer, using the platform from 2005 and leaving it with the Squarespace 6 launch in 2012 (due to a loss of functionality and flexibility that was in Squarespace 5 that a lot of Squarespace users today are completely oblivious to), this is a huge leap forward for WordPress in my opinion. In fact, with further proper refinement, I believe WordPress is on the home stretch now to surpassing the ease of use and flexibility of Squarespace which is amazing for an open platform.

    That said though, I’m sure it probably feels like a stumbling, confusing leap for a lot of developers (of which stepping into a new realm of possibilities and potential always is) but from my perspective, it looks remarkably like development for Squarespace 5 used to be. So as Justin noted, if you’re developing a theme for a singular client specifically, you can completely enter CSS code into your theme as you’ve always done.

    Yet if you’re designing a theme for sale to many users, you’ll want to use the theme.json so all of the styles applied to the blocks can be fully modified by the end user if desired. That’s because the design flexibility will be the paramount selling point for these. So the end user is using the theme as a starting point for their own design, rather than just as an end point.

    This is why Squarespace 5 was extremely popular with not just developers but designers even more so because they didn’t need to know HTML coding but only the basic understandings of how CSS worked to design a site within it. This was possible because it had a fully integrated CSS Style Editor within it (kind of like the WordPress 5.9 Styles area but on steroids) that was much more powerful than the one in Squarespace 7 today because you could modify the styles of a theme and export it as an XML file that someone else could import (like a WP child theme but just for style modifications).

    So what this creates is a larger tiered ecosystem whereby developers will have designers as their primary customers (because they don’t have the coding / scripting skills) and designers will have end users as their customers (because they don’t have the comparable professional design skills).

    • I just found the “Preliminary Roadmap for 6.0” and they’re actually implementing exporting & importing! Oh wow! This is amazing.

      “We have the opportunity to make the customizations applied to global styles also part of the export flow so that it can easily be migrated to another site, let’s make sure to include this in the consideration.”

  11. I don’t see block themes gaining that much traction immediately because the theme.json file, while a very good idea in principle, is very limiting right now. For example, one cannot set a hover/focus/active color for links, buttons and menus. Or style a specific block variation (e.g.: the “Outline” style in the Button block) or disable it.

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: