Automate Your WordPress Theme Development  > [!note]+ Document Notes > ```yaml > tags: [WordPress, Themes, Automation] > author: George Stephanis > source: WordPress.com > reference: [https://georgestephanis.wordpress.com/2026/01/06/automate-your-wordpress-theme-development/] > date created: 2026-01-07 00:00 > --- > # 🏷️ Title: Automate Your WordPress Theme Development > ## 🧭 Table of Contents > - [📝 Summary](#-summary) > - [📖 Main Content](#-main-content) > - [🗒️ Notes](#️-notes) > - [📚 References](#-references) > - [🗣️ Paraphrase](#️-paraphrase) > - [📰 Newsletter](#-newsletter) > - [✅ Action Items](#-action-items) > - [🧪 Hypotheses](#-hypotheses) > - [📊 Methodology](#-methodology) > - [❓ Questions](#-questions) > - [🔮 Future Research](#-future-research) > - [💡 Implications](#-implications) > - [🧠 Learning Styles Assessment](#-learning-styles-assessment) > - [📊 Accessibility Assessment](#-accessibility-assessment) > - [🌍 DEIB Assessment](#-deib-assessment) > - [✅ Logical Validity](#-logical-validity) > - [🛡️ DARVO Analysis](#-darvo-analysis) > - [🎯 Conclusion](#-conclusion) > ### 🔗 References > - Include links cited in or relevant to the article. > ## 📝 Summary > - What happened: The author built a reusable boilerplate and workflow to rapidly spin up Full Site Editing (FSE) themes from Figma designs using Create Block Theme, GitHub Actions, Composer/@wordpress/scripts, Sass, Playground, and Starter Content. > - Why it matters: Dramatically reduces repetitive setup, improves consistency, and enables easy client demos. > - Key stakeholders: Theme developers, agencies, clients reviewing designs, WordPress core/tooling teams. > - Risks and tradeoffs: Boilerplate can drift from best practices; automation hides complexity; Playground demos may differ slightly from production hosting. > - Bottom line: Investing in opinionated automation around FSE, Playground, and starter content pays off for recurring theme work. > ## 📖 Main Content > - The article starts from the need to ship many FSE themes quickly from Figma, motivating a “solid starter theme” instead of reinventing the wheel. > - The core tool is the **Create Block Theme** plugin, which lets you edit templates, headers/footers, colors, and typography in the Site Editor and then write those changes back into the theme on disk ([Create Block Theme section](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=00008_00002-003Q&startLexposition=00006&emphasizeText=it+then+gives+you+a+simple+option+to+write+your+changes+to+disk+in+the+theme+itself)). > - As a base, the author prefers starting from the official Create Block Theme boilerplate, which is minimal—header/footer partials, a basic index template, and a `theme.json` that you extend via the Site Editor ([boilerplate explanation](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000I_00000-004M&startLexposition=0000A&emphasizeText=There%E2%80%99s+really+not+a+lot+to+it.+A+header+and+footer+partial%2C+a+general+index+template%2C+and+a+theme.json+file)). > - He then layers automation: > - **Automatic namespacing** via a GitHub Action, adapted from Automattic’s Special Projects templates. Creating a new repo from the template triggers automatic renaming of the theme folder and namespaces to match the new theme name, replacing older fragile local string-replace scripts ([automatic namespacing description](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000Q_00001_00000-001f&startLexposition=0000K&emphasizeText=as+soon+as+you+use+the+boilerplate+to+create+a+new+repository%2C+with+one+click+you+can+have+the+theme+folder+and+all+the+namespaces+reflecting+the+new+instance%E2%80%99s+name)). > - **Build tools automation** using `@wordpress/scripts` for JS/CSS bundling and Composer for translations, PHP formatting, etc., wired in so everything works out of the box ([build tools section](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000Y_00002-000V&startLexposition=0000S&emphasizeText=That%E2%80%99s+why+I%E2%80%99ve+got+my+boilerplate+leveraging+a+lot+of+the+public+work+that+the+Special+Projects+Team+built)). > - For styling, the author likes Sass but increasingly uses `theme.json` for block theme styles so they’re editable via the Site Editor and avoid CSS specificity issues, while also improving WYSIWYG in the editor ([Sass vs theme.json reasoning](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000e_00000-006g&startLexposition=0000a&emphasizeText=I+find+I%E2%80%99ve+moved+more+toward+%28where+possible%29+defining+the+styles+in+theme.json)). > - A major feature is **WordPress Playground** integration: > - Playground runs WordPress entirely in the browser, without a server. > - The real value is instant test sites: clients or stakeholders can try a theme or feature via a link backed by the current GitHub repo state, once the boilerplate is configured ([Playground utility](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000o_00001_00000-000Q&startLexposition=0000g&emphasizeText=It+makes+it+trivial+to+set+up+a+test+site+and+let+a+user+%28or+client+or+stakeholder%29+instantly+test+out+a+plugin+or+trial+a+theme)). > - To avoid blank demo sites, he uses **Playground Blueprints** plus **Starter Content**: > - Blueprints can import WXR exports or run an `importThemeStarterContent` step, reusing the older Starter Content feature from WordPress 4.7 and adapting it for block themes ([starter content overview](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0000y_00005_00000-000V&startLexposition=0000q&emphasizeText=Starter+Content+is+a+feature+that+was+introduced+through+the+Customizer+way+back+in+WordPress+4.7)). > - A snag: Starter Content still imports classic nav menus, but FSE themes use navigation blocks: > - Core offers a class to convert legacy menus to block navigation, but it isn’t directly referenceable. > - The boilerplate runs custom PHP during Playground setup (via a Blueprint step) that can bootstrap a theme file, clean up imported Starter Content, fix permalinks, and reconcile navigation menus. > - Since navigation blocks only accept menu IDs, the author adds a custom slug property in templates that maps to the appropriate Starter Content menu, ensuring header/footer menus are wired correctly ([navigation handling and slug mapping](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0001C_00001_00000-000z&startLexposition=00010&emphasizeText=Finally%2C+core%E2%80%99s+navigation+block+only+supports+specifying+menus+by+ID+%E2%80%94+no+support+for+slugs)). > - He closes by acknowledging the boilerplate isn’t perfect but has saved significant client time and invites others to use it and build “super-cool-stuff” ([closing reflection](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=0001K_00000-0017&startLexposition=0001E&emphasizeText=For+me%2C+though%2C+it%E2%80%99s+a+great+starting+point%2C+and+has+saved+me+a+bunch+of+time+for+client+work.)). > ### 🗒️ Notes > - Motivation: recurring client work building FSE themes from Figma leads to creating a “solid starter theme” instead of repeating set-up work ([opening motivation](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=00004_00000-0025&startLexposition=00000&emphasizeText=Whatever+is+a+programmer+to+do+but+make+sure+I%E2%80%99m+being+efficient+and+not+reinventing+the+wheel+by+creating+a+solid+starter+theme.)). > - Create Block Theme (CBT): > - Acts as the main bridge between Site Editor customization and the theme files on disk. > - Encourages designing in the editor first, then persisting to the filesystem ([CBT description](https://read.readwise.io/read/01ked1m98mm01j3eptkpacmq36?endLexposition=00008_00002-003Q&startLexposition=00006&emphasizeText=While+you%E2%80%99re+editing+your+theme+in+the+Site+Editor+%E2%80%94+customizing+page+templates%2C+headers%2C+footers%2C+colors%2C+typefaces+%E2%80%94+it+then+gives+you+a+simple+option+to+write+your+changes+to+disk)). > - Boilerplate base: > - Uses the official CBT boilerplate repo, which is intentionally minimal and expects you to expand via Editor-made templates and patterns. > - `theme.json` is central for defining theme parameters and later editor overrides ([boilerplate rep Late last year I started working on an ongoing project that involved turning out a number of FSE (Full Site Editing)-based themes rather quickly from provided Figma designs.  Whatever is a programmer to do but make sure I’m being efficient and not reinventing the wheel by creating a solid starter theme. #### Create Block Theme When looking at Full Site Editing, probably the most useful tool to have on your belt is the **[Create Block Theme](https://wordpress.org/plugins/create-block-theme/)** plugin. While you’re editing your theme in the Site Editor — customizing page templates, headers, footers, colors, typefaces — it then gives you a simple option to write your changes to disk in the theme itself. #### Base for CBT When you start using Create Block Theme, it gives you options to either make a child theme of your current theme, or (my preference) start from a clean, blank boilerplate theme. For Create Block Theme, it’s this: <https://github.com/WordPress/create-block-theme/tree/trunk/assets/boilerplate> There’s really not a lot to it. A header and footer partial, a general index template, and a theme.json file that starts defining parameters. The idea is that you’ll start creating more templates and patterns in the Site Editor and then save them to the theme as needed. #### Automatic namespacing with GitHub Actions One of the things I was most delighted by building from my time on the Special Projects Team at Automattic was a GitHub Action we used when generating standard repositories from [a given template repository](https://github.com/a8cteam51/team51-project-scaffold). It was [a project I built out at a team meetup in Dublin for template repositories](https://github.com/a8cteam51/team51-plugin-scaffold/pull/4). Previously, some tooling was used on the command line to clone the scaffold repository into a local `tmp` directory and then do a local string/replace and finally push it back up to a new repository. This was relatively fragile, so this solution — handling the renamespacing — was a tremendous win. For our use case here, though, it means that as soon as you use the boilerplate to create a new repository, [with one click you can have the theme folder and all the namespaces reflecting the new instance’s name.](https://github.com/georgestephanis/theme-repo-template/blob/main/.github/workflows/fill-in-scaffold.yml) #### Build tools automation Build tools used to be a **nightmare** to set up. With the coming of the `@wordpress/scripts` package, however, it became significantly simpler to configure and run. However, there’s other tooling, such as generating translations, running PHP code formatting, and the like, that are best done in Composer instead. So, it’s nice when all your build tools are configured to work out of the box. That’s why I’ve got my boilerplate [leveraging a lot of the public work that the Special Projects Team built, and released](https://github.com/a8cteam51/team51-configs) for just this sort of utility. #### Sass Support When I need to write CSS, I prefer to write Sass. I find it easier to read, and easier to reuse. However, with Block Themes, I find I’ve moved more toward (where possible) defining the styles in theme.json — as that means they can be overridden in the Site Editor down the road, without having to worry about conflicts of specificity and ordering to ensure our selectors are behaving as expected. Plus, they’ll automatically work better in the Block Editor for more of a WYSIWYG experience, from what I’ve seen. #### Playground Support Finally, another aspect that I wanted to configure when spinning up themes was supporting [WordPress Playground](https://wordpress.org/playground/) functionality. WordPress Playground is a packaging of WordPress in such a way that instead of connecting to a web server (or even having a web server), all the PHP server-side code runs *in your browser directly*. This is kind of fun as a thought experiment, but it took me a while to really grasp the utility of it: It makes it trivial to set up a test site and let a user (or client or stakeholder) instantly test out a plugin or trial a theme. That can mean that when getting feedback on a feature, you can just link the client directly to an up-to-date Playground being powered by the current state of your GitHub repository. And once most of the configuration is set up in the boilerplate, [it’ll just work magically.](https://github.com/georgestephanis/theme-repo-template/blob/main/.github/workflows/fill-in-scaffold.mjs#L67-L70) #### Populating with Starter Content Anyone who has ever installed a theme and been instantly unimpressed can tell you what a let-down it is when every page is blank, and the site doesn’t look half as engaging as it did in screenshots. Fortunately, Playground supports Blueprints, which give us several ways to load content in. Firstly, it’s possible to bulk import content through a WXR (WordPress XML Export format) — [there’s a step for blueprints](https://wordpress.github.io/wordpress-playground/blueprints/steps#ImportWxrStep) where you can just give it the path to your export, and it will automatically pull it in. But perhaps more interestingly, [there’s a step called `importThemeStarterContent` instead](https://wordpress.github.io/wordpress-playground/blueprints/steps#ImportThemeStarterContentStep) — which gives us a lot closer to what we’re after. Starter Content is a feature that was introduced through the Customizer [way back in WordPress 4.7 — nearly ten years ago](https://make.wordpress.org/core/2016/11/30/starter-content-for-themes-in-4-7/). What a wonderful feature that just needs a little bit of love to bring it back up to scratching our itch here in the days of block-based themes, [and it does the job quite well.](https://github.com/georgestephanis/theme-repo-template/blob/main/_playground/starter-content.php) #### Starter Content Menus When navigation block menus were introduced for Block Themes, there was a change from the prior implementation of nav menus (under the Appearance menu). For one, navigation block menus can trivially have other types of blocks contained in them, that couldn’t have been represented well in the classic nav menu post type — so it had to shift over. The problem is that when theme starter content is imported, it imports as the pre-block nav menus. [Core offers a class to rewrite them on demand to block-based menus](https://github.com/WordPress/WordPress/blob/master/wp-includes/class-wp-classic-to-block-menu-converter.php), however, but they can’t be referenced directly. So, instead, [we can use *another* step to run some custom PHP](https://wordpress.github.io/wordpress-playground/blueprints/steps#RunPHPStep) when Playground is setting up the instance. Generally in the examples, it runs inline php, but there’s no reason we can’t just have it load a PHP bootstrap file from our theme instead! | | | --- | | `{``"step"``:` `"runPHP"``,``"code"``:` `"<?php require '/wordpress/wp-load.php'; include_once get_theme_file_path('_playground/setup.php');"``}` | Once that’s done, we just need to iterate through and [tidy up after the Starter Content import](https://github.com/georgestephanis/theme-repo-template/blob/main/_playground/setup.php) (and maybe do a few other tiny things like [configuring permalink structures](https://github.com/georgestephanis/theme-repo-template/blob/main/_playground/setup.php#L14-L16))! Finally, core’s navigation block only supports specifying menus by ID — no support for slugs. If we want to have distinct header and footer menus, then we can specify which goes where by adding a custom slug property in our template, that maps to the menu in our Starter Content — <https://github.com/georgestephanis/theme-repo-template/pull/1> #### Is It Perfect? No, of course not. But no project ever really is. For me, though, it’s a great starting point, and has saved me a bunch of time for client work. I hope you’ll find it useful, and make some super-cool-stuff with it., Automate Your WordPress Theme Development, George Stephanis, 01ked1m98mm01j3eptkpacmq36.