Building a Block Theme

I’ve been [badly] writing WordPress themes for this blog since sometime around 2006 or 2007. I learned pretty much everything I know about PHP (which isn’t a lot), from picking apart the stock theme and regurgitating it into my own design. Since then, I’ve become more and more comfortable with the traditional PHP, HTML and CSS way of writing a theme.

But times change and now we have block themes so I’ve tried an experiment to see if I can recreate my current theme, October, as a new all block theme: November. I haven’t pushed it live yet, and I’m not sure if I ever will, but I thought I’d put down some words here on the experience so far.

October and November themes

I’ve been a relatively early adopter of the Gutenberg post editor, even including it in a spec for a professional website project I was involved in during 2018 and 2019. I know there is a bit of controversy about the push towards the new editor and the ‘learnability’ of it compared to the traditional TinyMCE way of writing posts and pages, but I’ve found it so liberating, especially for professional work. I’ve been able to create no-code layouts that would be impossible with the classic editor.

So, finding a way to make this site quickly reconfigurable within a theme I know I’ve written myself is quite appealing. But also pretty difficult.

Are People Really Afraid of CSS?

The first thing I’ve struggled to get my head around is that there is a style.css file, but that it isn’t where the CSS goes. I guess it is still needed for compatibility, since it is where WordPress looks for theme information, but it feels wrong to have it sitting there, empty. On the other hand, the HTML templates and how they’re stored in neat directories feels a lot more logical than the free for all that classic themes allow for.

I followed a pretty good tutorial from, but a lot of the current documentation for block themes is a bit confusing. I am going to hazard a guess that large parts of it were written for earlier versions of the block editor, including versions prior to ‘full site editing’. That made my first attempts at getting templates to work more frustrating than I’d hoped for. But a large part of this is the mental shift needed to work well with block themes. My instinct is to try to write out the code for a template file, then check if it works right in the editor and on the front-end. This is not a helpful instinct. Instead, I’ve found it much easier to prepare the template layouts using the site editor, then work on styling in the themes.json file. It spits out the same code, so why not?

A Little More Handholding Would be Good

Another big mental shift, and one where a lot more documentation is needed, is writing styling information in a JSON file. The structure takes a minute to get used to, but more challenging are the subtle differences and apparent limitations in how to define styles. I’ve had to lean heavily on the theme.json file from the built-in TwentyTwentyThree theme, but that makes me feel like I’m limited to what that can do, not to what I could think up in CSS.

I’m going to stick with this and see if I can assemble a theme that I can push up here. I can feel I have a long way to go to get the block theme to parity with this (very basic) classic theme, but I think it will be worth the effort, even just to keep my skills something close to current.