Understanding Blockbase – A block base Parent Theme

Note: This post is part 3 of leaning efforts to understand and use full site editing (FSE) and block-based themes. This learning post is still in active development and updated regularly.

While I was working on the previous part 2 of this series, a new block-based theme Blockbase by Automattic landed in the WordPress theme directory. The Blockbase theme is dubbed as a parent starter theme for block themes just like _S starter for the classic themes.

With some features of Full Site Editing (FSE) being shipped slowly in the WordPress core, an understanding of showcase block theme like Blockbase is essential for creating block theme and WordPress site development. Unlike in classic themes, block themes are based entirely comprised on blocks.

Block themes use templates made entirely of blocks. The layout is configured using a combination of theme.json and CSS. The settings in theme.json are used to generate CSS – this is part of the Global Styles feature. The theme CSS is added after the theme.json CSS and together these rules define the layout for a theme. Ben Dwyer | Theme Shaper

Writing a review of Blockbase theme in WP Tavern, Justin Tadlock writesIt is the modern-day Underscores (_s) for blocks, and the WordPress theme design community will need such a project moving forward. They will need a starting point and educational tool, and Blockbase is just that. … It is a project that soon-to-be and current block themers can learn from.”

Learning series
Part 1: Global Styles and Global Settings
Part 2: Exploring Block Based Experimental WordPress Themes
Part 3: Understanding Blockbase – A block base Parent Theme (this post)

The main objective of this learning post is to get familiarize with Blockbase theme file structure, its styling via theme.json and use of custom settings for the styles that are currently missing in Gutenberg block editor.

Please note that the Blockbase block theme is active in development, the file structure and code snippets described here may be different depending upon when the post read. Please refer this Blockbase GitHub repository for the latest version.

Blockbase File Structure

Blockbase file structure from Automattic Themes GitHub repository is as follows:

#! blockbase file structure
|__ style.css
|__ functions.php
|__ index.php
|__ theme.json
|__ block-templates
    |__ index.html
    |__ blank.html
    |__ singular.html
    |__ search.html
    |__ 404.html
|__ block-template-parts
    |__ header.html
    |__ footer.html
|__ Assets
    |__ svg
    |__ ponyfill.css
|__ sass
    |__ ....
    |__ ....

Blockbase follows a minimal but essential file structure as described in block editor handbook. The starter theme includes two additional templates 404.html and search.html in the block-templates folder.

The theme describes it as a starting point and includes ponyfill.css styling file which is generated using sass build process. The theme documentation describes the goal of pony fill styling is “to reflect what Gutenberg will style, from a given configuration, once that work is complete. But to offer that today, using simpler techniques that Gutenberg will use upon completion.”

A more detail description of other files, template-parts (header.html, footer.html) and template-parts (index.html, singular.html …) is described in a previous posts and block editor handbook.

Functions.php File

The function.php file of Blockbase contains standard theme_support() function hook that is recommended to included in block themes to enable basic block support in the theme.

The following partial functions.php file taken from Blockbase GitHub repository showing how google fonts can be plugged in functions.php and out of theme.json file.

/* Blockbase functions.php file */

/* Blockbase theme support hook */

// ...

/** Enqueue scripts and styles. */
function blockbase_editor_styles() {
	// Enqueue editor styles.
add_action( 'admin_init', 'blockbase_editor_styles' );

/** Enqueue scripts and styles. */
function blockbase_scripts() {
	// Enqueue Google fonts
	wp_enqueue_style( 'blockbase-fonts', blockbase_fonts_url(), array(), null );
	wp_enqueue_style( 'blockbase-ponyfill', get_template_directory_uri() . 
      '/assets/ponyfill.css', array(), wp_get_theme()->get( 'Version' ) );
add_action( 'wp_enqueue_scripts', 'blockbase_scripts' );

/** Add Google webfonts
 @return $fonts_url */

function blockbase_fonts_url() {
	if ( ! class_exists( 'WP_Theme_JSON_Resolver_Gutenberg' ) ) {
		return '';

	$theme_data = WP_Theme_JSON_Resolver_Gutenberg::get_merged_data()->get_settings();
	if ( empty( $theme_data ) || empty( $theme_data['custom'] ) ) {
		return '';

	$custom_data = $theme_data['custom'];
	if ( ! array_key_exists( 'fontsToLoadFromGoogle', $custom_data ) ) {
		return '';

	$font_families   = $theme_data['custom']['fontsToLoadFromGoogle'];
	$font_families[] = 'display=swap';

	// Make a single request for the theme fonts.
	return esc_url_raw( 'https://fonts.googleapis.com/css2?' . implode( '&', $font_families ) );

Commenting on this unique technique, Justin Tadlock writes in WP Tavern that this method may “allow child theme authors to declare fonts in their own theme.json files and for Blockbase to handle the loading“.

Block Template Parts

The block-template-parts folder contains two theme parts <strong>header.html</strong> and <strong>footer.html</strong>.

Its header.html file is much simpler than TT1 Blocks theme make use of single wp:group block.

<!-- wp:group {"align":"full","className":"site-header"} -->
<div class="wp-block-group alignfull site-header">
	<!-- wp:site-title /-->
	<!-- wp:navigation {"isResponsive":true} /-->
<!-- /wp:group -->

Blockbase footer.html file (below) is simple paragraph wrapped inside wp:group block.

<!-- wp:group -->
<div class="wp-block-group">
	<!-- wp:paragraph {"align":"center","fontSize":"tiny"} -->
	<p class="has-text-align-center has-tiny-font-size">Proudly Powered by WordPress</p>
	<!-- /wp:paragraph -->
<!-- /wp:group -->
Block Templates

Blockbase contains following five templates blocks – index.html, singular.html, search.html, 404.html and a blank.html (an empty file).

Because the file structures of index.html and singular.html contain similar blocks that are discussed in detail in previous part 2 post, their explanation is avoided here.

Index.html File
<!-- wp:template-part {"slug":"header","tagName":"header",
 "layout":{"inherit":true}} /-->

<!-- wp:query {"className":"page-content","tagName":"main","layout":{"inherit":true},
  "tagIds":[],"order":"desc","orderBy":"date","author":"","search":"","sticky":""}} -->
<main class="wp-block-query page-content">
<!-- wp:query-loop -->
	<!-- wp:post-title {"isLink":true} /-->
	<!-- wp:post-featured-image {"isLink":true} /-->
	<!-- wp:post-excerpt /-->
<!-- /wp:query-loop -->
<!-- wp:group {"layout":{"inherit":true}} -->
	<div class="wp-block-group">
	<!-- wp:query-pagination -->
	<div class="wp-block-query-pagination"><!-- wp:query-pagination-previous 
          {"label":"Previous Page"} /-->

		<!-- wp:query-pagination-numbers /-->

		<!-- wp:query-pagination-next {"label":"Next Page"} /--></div>
	<!-- /wp:query-pagination -->
	<!-- /wp:group -->
<!-- /wp:query -->

<!-- wp:template-part {"slug":"footer","tagName":"footer","layout":{"inherit":true}} /-->
Singular.html File
<!-- wp:template-part {"slug":"header","tagName":"header",
"layout":{"inherit":true}} /-->

<!-- wp:group {"layout":{"inherit":true},"className":"post-header"} -->
<div class="wp-block-group post-header">
<!-- wp:post-title /-->
<!-- /wp:group -->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group post-content">
<!-- wp:post-featured-image {"align":"full"} /-->

<!-- wp:post-content {"layout":{"inherit":true}} /-->
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer",
 "layout":{"inherit":true}} /-->
Search.html and 404.html Files

The blockbase theme following two search.html and 404.html pages.

search.html File
<!-- wp:template-part {"slug":"header","tagName":"header","layout":{"inherit":true}} /-->

<!-- wp:group {"layout":{"inherit":true},"className":"page-content","tagName":"main"} -->
<main class="wp-block-group page-content">

<!-- wp:heading -->
<!-- /wp:heading -->

<!-- wp:query {"queryId":1,"query":{"perPage":10,"pages":0,"offset":0,"postType":"post",
  "exclude":[],"sticky":"","inherit":true}} -->
<div class="wp-block-query">
<!-- wp:query-loop -->

	<!-- wp:post-title {"level":5,"isLink":true} /-->
	<!-- wp:post-excerpt /-->

<!-- /wp:query-loop -->
<!-- /wp:query -->

<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer","layout":{"inherit":true}} /-->

The search.html file is structurally very similar to index.html template, with header.html, footer.html and a main wrapper containing a query loop block and a heading block (lines: 6-8).

404.html File
<!-- wp:template-part {"slug":"header","tagName":"header","layout":{"inherit":true}} /-->

<!-- wp:group {"layout":{"inherit":true},"className":"page-content","tagName":"main"} -->
<main class="wp-block-group page-content">

<!-- wp:heading {"level":1,"fontSize":"large"} -->
<h1 class="has-large-font-size">Oops! That page can’t be found.</h1>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>It looks like nothing was found at this location. Maybe try a search?</p>
<!-- /wp:paragraph -->

<!-- wp:search {"label":"","buttonText":"Search"} /-->
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer","layout":{"inherit":true}} /-->
The 404.html template is a very simple template with header.html, footer.html and main group wrapper containing page header and paragraph blocks. In addition, it also contains a search block with a ‘search‘ button.
Blockbase is a Representation of Theme Styling

In the theme announcement post, Ben Dwyer from Automattic theme team writes that their team is currently using blockbase as a starter parent theme for all their block-based themes.

Blockbase is intended to be a representation of all the theme style settings that we believe should eventually live in Global Styles and be configurable by users. Some themes need customizations beyond what would be possible with Global Styles. These more unique styles continue to be defined in the theme CSS file. Ben Dwyer | Theme Shaper

Global Styles

Because not all theme styling features are currently available in Global styles via theme.json, Blockbase demonstrates how missing, but common CSS styling features could still be added via Custom settings in theme.json.

theme.json File

Blockbase <a href="https://github.com/Automattic/themes/blob/trunk/blockbase/theme.json" target="_blank" rel="noopener">theme.json</a> file is much detailed than that of  TT1 Blocks theme (a default block theme) and the following is an outline from Blockbase GitHub repository showing “custom” and core settings CSS rules.

"version": 1,
	"templateParts": [
			"name": "header",
			"area": "header"
			"name": "footer",
			"area": "footer"
	"customTemplates": [
			"name": "blank",
			"title": "Blank",
			"postTypes": [
	"settings": {
		"border": { },
		"color": {
			"gradients": [], "palette": [] },
		"custom": {
			"alignment": { },
			"button": {},
			"code": {
				"typography": {}
			"color": {},
			"form": {},
			"gallery": {
				"caption": {}
			"heading": {
				"typography": {}
			"list": {}
			"margin": {},
			"paragraph": {},
			"post-author": {},
			"post-content": {},
			"pullquote": {
				"citation": {},
				"typography": {}
			"quote": {
				"citation": {},
				"typography": {}
			"separator": {},
			"table": {
				"figcaption": {}
			"video": {
				"caption": {}
		"layout": {
			"contentSize": "620px",
			"wideSize": "1000px"
		"spacing": {},
		"typography": {}
	"styles": {
		"blocks": {
			"core/button": {
				"border": {},
				"color": {},
				"typography": {}
			"core/code": {
				"spacing": {
					"padding": {}
				"border": {}
			"core/heading": {},
			"core/navigation": {},
			"core/navigation-link": {},
			"core/post-content": {},
			"core/post-title": {},
			"core/post-date": {},
			"core/pullquote": {},
			"core/separator": {},
			"core/site-title": {},
			"core/quote": {}
		"color": {},
		"elements": {
			"h1": {},
			// ...
			"h6": {},
			"link": {}
		"typography": {}

In the Blockbase release post, Ben drawer highlights the code size between the classic theme and a block-based theme and writes that Blockbase codes are only about one-fourth (1000 lines of code) compared to over 4000 lines of codes in its parent classic theme.

Blockbase as a Parent Theme

According to Ben Dwyer, these customization settings are intended to cover all representative theme styling and could easily modified via child-theme.json file so that Blockbase could be used as a parent theme.

In the “How it Works” section, Ben describes how Blockbase theme is intended to work in child themes of Blockbase:

  • Blockbase theme defines the most common theme styling CSS rules in theme.json file under “settings” and “custom” properties that are processed as CSS variables by Global styles.
  • With Blockbase block theme, its child theme could be easily built by simply redefining different setting values in a child-theme.json file and “a script will generate a theme.json file, taking the defaults from Blockbase and updating it with the new values from the child theme“.
Building a Blockbase Child Theme

The following a more detailed instructions on building Blockbase child theme adapted from the Blockbase readme file:

  • Add a package.jsonstyle.css and empty index.php files to your theme.
  • Your child theme’s theme.json file will be built by combining Blockbase’s original theme.json file and your child’s child-theme.json. That is the file where your configuration values live (you only want the values for variables that are different from the parent there).
  • To generate the combined file, run npm run build from inside your theme’s folder or run npm run build:child child-theme-slug from inside Blockbase’s folder.
  • Extend the parent’s templates that you want to customize or add new ones where needed following the template hierarchy.
  • Using npm run start will both watch changes inside the sass and assets folder and changes to the child-theme.json file.

The block themes are designed to work with FSE only.

Note on Universal Child Theme

There is brief note on creating Blockbase child themes in this readme file. Although this concept is in early explorative stage, Automatic designer Kjell Reigstad already has a use case example post in ThemeShaper where he explains how he created a Blockbase child theme named gitchy (GitHub repository here) just changing a few variables in Blockbase child-theme.json file.

Universal or Hybrid Themes

Theme teams (Automattic, WordPress) are discussing a concept of “universal theme” that works both with FSE as well as in the classic customizer context. Here is a link to follow GitHub discussion on hybrid themes as well as universal themes.

Recently, WordPress Theme development team also had hallway Hangout over zoom to discuss “universal theme” and a recording of the discussion is available on this YouTube.


Automattic themes team is currently working on prototype universal theme Quadrant, which at the of writing, is in very early stage of development. To learn more about this theme and keep up to date on its progress follow this project link at the GitHub.

Likewise, the WordPress Theme team is also discussing to Recreate Twenty Twenty Blocks as a universal or hybrid theme to “showcase what can be done already using global styles on an existing site“.

Using Blockbase Theme

To use Blockbase theme, Gutenberg plugin is required. In my test site, I have already installed and activated Gutenberg plugin.

Blockbase is available from WordPress theme directory for download. It can be added directly from the admin dashboard Appearance > Themes > Add New.

Once the Blockbase theme is activated, the appearance button disappears and Block Editor Beta button appears. Just like in classic themes, if we visit the site (front end), list of posts are displayed in the front page with page navigation, and a footer. All the links work as expected.

Screenshot showing list of posts in the Index.html template.

A screenshot of footer section of the index.html template showing page navigation and footer credit.

Screenshot showing page navigation block and footer block credit.
Adding Menu

In classic themes, we are used to adding site menu either through Appearance > Customize or Appearance > Menus windows then selecting menu locations.

In block themes, menu is available through Navigation Block available via Block editor. The Navigation Block is “an alternative to the more commonly used WordPress menu options. Just like in the default TT1 Blocks theme, the Navigation Block adds empty placeholder state for primary navigation.

Using FSE, menu can be added by following three methods:

  • Using an existing menu: Selecting from an already created menu (just like in classic themes).
  • Create from an empty: In this method, links such as Home Link, page link, posts link can be added in the navigation (see screenshot below)
  • Create from all top-level pages: This adds all the top-level existing pages from the site.
Screenshot from WordPress.com

For more detail, this Blocks >> Navigation Block documentation from WordPress.com describes how menu is added with easy to follow screenshots.

In the following screenshot, a preexisting menu with sub menu-items was selected in Blockbase theme.

Screenshot showing top level navigation block (responsive) in Header block template parts.
Wrapping Up

In this learning post, file structures, template-parts, block templates and other files were explored. Because the Blockbase is a bare-boned basic block theme structure and styled via its global theme.json file, there is a lot more to chew on theme.json which we will further explore by modifying Blockbase theme in the next learning post.

Resources and Credits

The following is list of references link that I gathered during my brief research. While preparing this post, I have also referred some of the following references extensively. Please to refer original posts for more detailed information.