We recently released Course, a block theme for Sensei LMS. While we are experienced WordPress plugin developers, this was our team’s first foray into building a block theme (or any theme, for that matter). We thought we’d share here how it went for the benefit of others.
Key Decisions
We wanted to take advantage of the latest and greatest in WordPress, but we also wanted the theme to be able to be used as easily as possible. We decided early on that installing the Gutenberg plugin would not be a requirement for using our theme. We also decided that we would only support WordPress 6.1+, which was set to be released just prior to the release of Course. This enabled us to take advantage of features like fluid typography.
Work Breakdown
Having never built a block theme before, we weren’t sure what the task breakdown should look like. Which templates would we need to create or customize? Where should we begin?
Happily, in the Automattic themes repo we found a handy checklist of GitHub issues that that team creates when building a new theme. This checklist formed the basis of our initial development tasks.
Creating the Base Theme
We used Block Canvas as a starting point for Course. Block Canvas is a simple theme developed by Automattic that supports full-site editing. It comes with a set of minimal templates and design settings that can be manipulated through Global Styles.
In order to get started with Block Canvas, we installed the Create Block Theme plugin. This plugin enables you to create a new theme from the currently activated theme. The resulting theme has all of the assets of the activated theme, as well as some customizations specific to the new theme (e.g. the name and description).
You can follow these steps to clone Block Canvas:
- Install and activate the Block Canvas theme.
- Install and activate the Create Block Theme plugin.
- Navigate to Appearance > Create Block Theme.
- Select the Clone Block Canvas option.
- Fill out the details for your particular theme.
- Click the Generate button, which will download a zip file containing the customized version of Block Canvas.
- From there, you can upload and activate the starter theme in Appearance > Themes.
Developing the Theme
With the base theme in place, we focused on styling first. We added theme colors, typography settings, and updated styles for blocks like buttons and headings. These were all foundational changes to be leveraged later in the theme’s patterns and templates.
Our workflow for building patterns and templates was to use the Site Editor to create them, and then copy the markup to the appropriate HTML theme files. To save manual work, we used the Create Block Theme plugin to automatically update HTML files by selecting the Overwrite Course option:
However, there were a few instances where this didn’t work so well. For example, some templates like the 404 page utilized PHP-based block patterns so that its text could be translated. The Create Block Theme plugin doesn’t handle this use case and would overwrite everything in the 404.html file instead. In cases such as this, we had to rely on the good old-fashioned copy / paste method (and also needed to check to ensure that we didn’t clobber any existing translations in the process).
Challenges
As you might expect, building a block theme was not without its challenges. Here are a few that we encountered:
- Frequent conflicts in
theme.jsonwith multiple developers working on the theme. Occasionally we’d change things that broke something elsewhere without realizing it. - Although we tried to do as much as possible in
theme.json, it wasn’t always possible (e.g. responsive navigation menu), and we had to introduce some custom CSS. - We wanted to add a Sensei-specific template (i.e.
single-course.html) from the plugin instead of baking it into the theme. However, due to some technical challenges, we opted to simplify and add it directly to the theme instead.
Submitting to WordPress.org
Prior to submitting our theme to WordPress.org, we performed an audit to ensure it met the theme requirements. The submission process itself was straightforward – just upload a .zip file and you’re done!
Well, almost.
Our first submission was actually rejected because it was missing image and font copyrights. We fixed that, resubmitted, got approved, and the rest is history!
Next Steps With Course
We’ve been happy to see downloads and installs growing with Course. We will continue to improve the theme and support any relevant new features or changes in the Block Editor, Sensei LMS, or WordPress core.
We’re also happy to take any community contributions and may add additional Style Variations as usage of the theme grows.
If you haven’t yet, you can download the Course theme here.
Leave a Reply