Switching to a block-based theme

You might not notice a difference, but this site is now using a block-based theme. I’ve been tinkering with this on and off for the last few months. I’d get halfway there, then run into some issue with it not being stable, and put it down for a while. Since Twenty Twenty-Two will be a block-based theme, I thought it would be a good time to try again.

The current iteration of the theme is on github at ryelle-codes-2022.

Github card. ryelle/ryelle-codes-2022: A block-based theme for ryelle.codes.

My process

The design of the site would stay the same, I like the current iteration. That theme also used theme.json, even though it was a “classic theme”, as a way to set up the custom properties. When I started this theme, I needed to create the HTML templates & template parts, and move some block CSS into theme.json configuration.

I wanted to develop this locally & deploy it to my live site when it was done, so I tried to do all my editing in the HTML files. I thought that would help me be intentional about what’s in each template — in the past I’ve had trouble with stray paragraph tags and such. Unfortunately, you need to know what attributes to use for each block, so it ends up being trial and error and/or reading the block source code. I used a lot of random draft pages where I tweaked something & looked at the code view to see how the block syntax worked.

I would have used the site editor itself more, but the code view is disabled there.

Most of the basic styling I wanted to do could be done with theme.json configuration, but it was a little tricky to navigate between “this is how I would do it in CSS” versus “theme.json needs it this way.” At the start, I missed the cascade of CSS and felt like I was repeating myself a lot. My site is simple enough that I didn’t need to defined many elements or blocks, if I did, this might’ve bothered me more.

How it went

Like I mentioned, I started this months ago. Since then, there have been changes. A new version of theme.json, and very little documentation about what changed. At some point, the folder names for templates changed, from block-templates to templates & block-template-parts to parts. In both cases, the old things still work, but I’d rather stay up to date.

I thought I’d need to make a different site header, since my old-theme’s header was an inline SVG. I was initially using a group block with a gradient background, but I didn’t like the gradient. I mentioned that I was disappointed about this to Mel, and she suggested a Cover block with an SVG background. I was so stuck on it being an inline SVG, I didn’t even think of that. Also, I forgot about the Cover block 😅

I’m using Safe SVG to allow SVG uploads, and then used it like normal with the Cover block. It’s not exactly the same (the lines resize now, instead of staying 2px tall), but it’s much better than the gradient I hated.

I ran into a few things that felt like limitations or bugs. Some of them already have fixes in progress too.

  • #35355: If you put things in a group, there’s no way to switch that to an inline row, despite Row being a variation of Group. There’s an issue and a PR, so maybe this will be possible soon.
  • #37036: In a group block, you can toggle “inherit default layout”, which keeps the inner content from going full-width. That setting doesn’t exist for the Cover block, so when I rebuilt my site header, I had to add specific CSS to handle the width.
  • Initially I had my “content” template part nested inside a wp:query block, so that the template handled the query but my content partial would handle the display. I think this broke the context passing from the query down to query-pagination, so I had to move the query block into the template part. I don’t know if I’d really call this a bug, but it was unexpected.
  • When I activated the theme on my live site, the navigation block no longer matched a real menu. Easy enough to fix in the Site Editor, but now it no longer uses part/header.html, it uses a customized version. So if I edit the template part, I need to revert it to the file, and reset that navigation menu (I think). This probably isn’t a bug, but it still messes with my expected workflow.

I still don’t know how I’m supposed to add hover/focus states to links and buttons, so I guess that’s stuck in CSS. My link color is set using styles.elements.link, but I ended up resetting it in the CSS so I could also keep the text-decoration and other styles in one place. Buttons don’t have any hover/focus style at the moment, which I consider a bug in my theme.

Anyway, this post is pretty long now, so I’ll wrap it up. It was a fun experiment to refresh this site, and I really see the promise of block-based themes for easy site building. It’s a new framework to get used to, and sure there are bumps to work through, but it’s going to be great.

Posted in:



  1. […] Choyce-Dwan, core contributor on the meta team, takes you along her journey while switching to a block based theme. She shares with you her process and her challenges and how she overcame them. Choyce-Dwan also […]
  2. […] Visit Direct Link […]
%d bloggers like this: