Notes on building WordPress themes in 2026

I wanted to align the design of this blog with the design of my new1 personal website. As the blog runs on WordPress this required building a new WordPress theme. Whilst I do look after some WordPress websites and need to occasionally delve into the code I am not the full-time WordPress developer that I used to be. So I actually hadn’t built a WordPress theme from scratch for quite a while. The last time I did so the Gutenberg project was already well underway but I had chosen to more or less ignore it and to continue with building “classic” themes. A lot has changed in the WordPress world since then. To be fair I had allowed for some use of the block editor so maybe you could call some of the themes I built “hybrid” but they certainly weren’t doing the full site editing (FSE) that the current block themes do. In short my skills and approach were out of date. So the challenge was to build a WordPress theme for use in 2026 using an approach to theme development of 2026. I soon realised that building modern themes is actually very different, requiring not just new knowledge but a shift in mindset. Firstly there was (almost) no writing of PHP required. So my past experience of struggling with the query loop, trying to remember the right core functions, and writing my own functions wasn’t really needed. Also there was no need to know any JavaScript either. My knowledge of CSS was useful but the whole approach to styling was also different. The fact that I didn’t have to create or edit a stylesheet is one of the things I found most weird. What there is is a collection of files containing commented HTML markup. These define the display of blocks. All the template files are just containers for these block definitions. So you have to get your head around the fact that what you are doing is essentially specifying blocks within blocks within blocks. The second thing I think it is important to realise is that what you are coding in your HTML is not a theme that defines the look of the website in a fixed way. Instead, you are providing a set of guidelines – drawing an outline for others to colour in. The theme should provide a framework that users can then customise within the site editor. Choices of style and layout can be changed and overridden. So what determines the look of your website is a combination of what is specified in the theme files and the configuration choices stored in the database. In that way theme-ing is more multilayered than it used to be. The balance of what gets determined in the theme and what gets configured in the editor is something you have to constantly keep in mind. Obviously it will vary between projects – but even in building a theme for my own personal website I discovered it helps to take a step back and put a limit on how much you try to do with the theme itself. Theme-ing a WordPress is now a two-step process: you choose or build your theme and then using that as a base you design it in the site editor. This was a bit of a shift for me, as my natural instinct is to specify everything in the code. Workflow and tools This two-step process became very obvious as I began to work on the theme for this blog. So in case it might help anyone I will say a little bit about my workflow for building the theme and the tools that I used. My starting point was the WordPress Theme Handbook. This has a really good introduction to how to get going with theme development and I found that most of the information I needed could be found there. Having familiarised myself with the basics I setup a local WordPress install, a WordPress website running on my local computer, to use as a development environment. I used the tool ‘Studio by WordPress‘ to do this because it makes it really quick and easy to get up and running. From within the WordPress admin of the local site I installed some of the recommended development plugins: Theme Check, Debug Bar, and Query Monitor; as well as importing the standard collection of theme test data. Most importantly I installed the Create Block Theme plugin. This is an essential tool. It allows you to quickly clone the theme you are working on, create a new blank theme that you can use as a starting point, and most critically when you are ready export your theme into a Zip file for distribution. It kind of helps you to bridge the gap between working in the site editor and working in your code. I used Visual Studio Code as my code editor. Note that you need to make a note of the location of where the files for that local website are stored. It is within the /wp-content/themes/ folder that the files for your theme live. You need to create folder there for each theme that you are building. I use GitHub for source control so I needed to create a new repository for each theme and clone it into the themes folder. So there is a little bit of fiddling about making folders and copying files until you get properly setup. Once you are setup you can start to build your theme. But you do not start with writing code. You start in the site editor making modifications to an existing theme. Once you have got something you like, the Create Block Theme plugin allows you to export the theme with your modifications as files into a theme folder. You can then open that folder in your code editor and make changes from there. I found that in practice I was going back to the site editor to work on elements, collections of several blocks combined, copying the HTML code for those blocks into the code editor, before tidying it up and adjusting it. This moving back and forth between the two, site editor and code editor, is what made me realise the significance of the “two-step” process mentioned above. Also this process of working with collections of blocks and then saving the resulting code in files made me appreciate the importance of theme patterns as a tool to use in making your theme work coherently. I would suggest that a good tip for a beginner to block theme development would be to pay attention to how patterns work and how they are used in templates. Another lesson is to “let go” of CSS. Often for me web development has involved starting with a CSS reset and some basic styles or choosing a CSS framework and using that to layout templates. Do not approach block theme development that way! Do your layout, choose your colours, set your typography in the site editor and then export it. Note that most of those settings will be stored in the theme.json file. Another important lesson, given that this workflow assumes that you build a theme by modifying an existing theme, is to think carefully about what you are using as you base theme. Three bears like, I started with using the latest default WordPress theme, Twenty Twenty-Five, but that came with too much stuff and I got confused. I used the Create Block Theme plugin to output a “blank” theme, but that really was blank and contained too little. So in search of something that was just right I ended up developing my own block starter theme. My starter block theme My WordPress block starter theme, which is still rough around the edges, is available for download from GitHub at: https://github.com/grit-and-oyster/oystershell-block-theme This is not a completely blank theme. It has a number of settings and template files added so you aren’t starting completely from scratch but it is mostly empty of design choices. It includes: Templates index.html – the default/fallback template and the main template for listing posts single.html – a single post template page.html – a static page template search.html – the template for search results 404.html – the template for displaying 404 page not found errors Template parts 2 parts used in all the above templates. header.html – with site logo, site title, tagline, and menu footer.html – mostly empty Patterns A number of block patterns that are used by the theme templates. Two patterns hidden from the editor that provide default functionality for comments and the search box. hidden-comments.php hidden-search.php Three patterns for key repeated elements available in the editor for easy customisation that provide two areas for displaying post meta and the post-to-post navigation. post-meta-bottom.php post-meta-top.php post-navigation.php Other files Standard license and readme files etc. functions.php – includes two functions; one for removing access to the core block patterns and another for registering a custom block pattern category theme.json – includes details of a few essential settings but otherwise empty My blog theme Using the above theme as a base I then modified it to match the design of my personal website to create the theme for my blog. I haven’t got them matching exactly but I have done a pretty good job I think. This theme includes all the features of my starter theme with the header, footer, post meta further customised. In addition the theme.json file defines: the colour palette a larger content width the inclusion of the Inter and Bebas Neue fonts and their use a range of standard font sizes some basic styles The functions.php file contains some additional functions to display a small banner that states the original source of certain posts associated with specific authors. This identifies posts that have come from previous blogs and websites. This code was directly copied from the old theme for this blog. The only modification is to convert the output to use the commented HTML markup common to blocks. I also added an additional block pattern to manually insert the above banner in case I want to include it in future posts. Further notes This redesign process has left me more positive about modern FSE block themes than I was before. To be honest I was a bit dubious before. But now I can see where this approach could be quite powerful. One minor annoyance is that I really can’t see how to get the pagination for a list of posts to display nicely. Also I find the menu system really confusing. One of the really good features of the old way of theme-ing in WordPress was the way you could configure and manage a collection of menus. This seems to be mostly missing in block themes. Finally, although I have just been saying how you should be “relaxed” about not needing to write CSS, I do really need to work out how to include and apply a custom stylesheet to a theme.