An Introduction to Block-Based Homepages with Genesis Framework

StudioPress recently released Revolution Pro, the first Genesis child theme to sport a block-based homepage.

If you’ve been around StudioPress and Genesis (or heck, just WordPress) for awhile, you’re familiar with the concept of a widgetized front page. Widgets weren’t really ideal as a layout tool, but they made it possible for theme developers to create attractive home page layouts that people could take advantage of even if they didn’t know code.

Host your WordPress site with WP Engine and get Revolution Pro them for free.

So it’s what we used.

But what if you could take advantage of the Gutenberg block editor for a home page layout? You can and StudioPress shows us how with Revolution Pro theme (and the Genesis Sample theme, too).

This post includes affiliate links. Every time you click and buy, I raise a toast to you from my yacht!

Why are blocks better than widgets for a home page?

In this WordPress 5.0+ block editor era, there’s no reason we can’t use blocks to create better home page layouts. As a matter of fact, it’s superior to widgets for multiple reasons.

1. Hard-coded widget areas for a specific layout

Let’s say you’ve got a home page with 4 widget areas used to display content in 4 columns. Looks nice, yeah?

4 widget areas on a homepage

But what if you only want 3 columns. Or 5 columns?

If you wanted to add an extra widget area, you’d need to register a new widget area. If you want to change the number of columns, you’d need to change the supporting CSS (across all relevant break points).

While some of the newer Genesis child themes (i.e. Essence Pro, Infinity Pro)  are flexible enough to account for those changes, most are not and would require getting into the code to change.

Blocks, like honey badgers, don’t give a $h!t about widget areas.

2. Hard-coded styles for specific widgets

Home page styles were frequently designed for a specific type of widget and looked weird if you wanted to use a different widget. For example, let’s say the Header Right widget area was pre-styled for a search widget, but you wanted to use a navigation menu widget there instead. Unless the theme developer accounted for styles for a menu in that widget area, it’d look like crap. ?

3. Your front page is actually… your front page

Creating a dynamic front page (i.e. a front page made up of widget areas) historically involves:

  1. Registering desired widget areas in functions.php
  2. Creating a front-page.php template file to display widget areas
  3. Create a Page. Call it “Home” or “Front page” – the name doesn’t matter. Leave this page empty.
  4. Go to Settings > Reading > Front Page Displays > and set that to the page created in Step 2.

With a block-based home page, you eliminate the first two steps. Now, you just create a Page, use the block editor to lay it out / design it, then set it to display as your Front Page.

This is so much more intuitive for users to have an actual Page you can directly edit vs messing with a bunch of widgets.

Editing a block-based home page

Those are just a handful of examples of how widgets are limited in their flexibility and usage. Blocks, on the other hand…

Create a block-based homepage

Hopefully you’re on board with me that blocks beat widgets in terms of simplicity and intuitive use. If so, let’s take a look at how to create a block based home page.

Method 1: I want to create a block-based homepage for my site

Good news. This is easy. First, you either need to have WordPress 5.0+ installed (and are using the block editor) OR you need to download the Gutenberg plugin for use with anything older than WP 5.0. (For the record, if you’re still on an older version of WordPress, why??)

Then, simply follow these steps:

  1. Create a page. Use the block editor to create a beautiful layout.
  2. Go to Settings > Reading > Front Page Displays > and set that to the page you want.

Hoping for something harder? Too bad, that’s it.

Method 2: I’m a theme developer and want to add block-based homepages to my themes.

In this scenario, we want to “bake in” a home page that uses the block editor in a pre-set layout, like the Revolution Pro theme does. Then, when a user installs your theme, they go through the theme onboarding process (requires Genesis 2.8+).

That user experience looks like:

  1. Install/activate theme
  2. Click the “Set up Homepage” button
  3. Sit back and watch the beauty unfold
  4. Go edit the freshly created home page (pre-populated with demo content!) to add their content

The developer experience is, well, more complex. That roughly involves:

  • Create a file with the block markup (layout) and content you want to use for the front page
  • Include any images you want to use on the front page
  • Create a page template (used as the template for the front page)
  • Create an onboarding file (used to load plugins, create the front page, and load theme demo content)

While you can find the documentation for the onboarding process here, I wanted to conceptually explain how it works.

Code logic and load order

As a theme developer, you’re familiar with the role of the child theme’s functions.php. Imagine we’re stepping through functions.php (only as far as the onboarding process goes)…

At some point, the Genesis Framework is called to come play. A lot of StudioPress themes do that like this:

// Starts the engine.
require_once get_template_directory() . '/lib/init.php';

In other themes, you might just see child theme setup stuff hooked directly into Genesis, like this:

add_action( 'genesis_setup', 'child_theme_setup', 15 );

However you want to do it, Genesis is loaded via a child theme’s functions.php.

Important note here: The Genesis Framework handles all the logic for the onboarding sequence.  From here on out, Genesis will look to the child theme for some files, but the logic is handled within Genesis.

When the framework loads, it goes looking for a file called onboarding.php within the framework. THAT file then goes hunting for config/onboarding.php in the child theme.

No onboarding file present?

If the child theme doesn’t have a file called onboarding.php inside of a /config folder in the theme root, then no further onboarding happens. If you tried to trigger the onboarding sequence by going to /wp-admin/admin.php?page=genesis-getting-started, you get this error:

Error window saying Sorry, you are not allowed to access this page.
Onboarding file present -> PROCEED!

The child theme’s onboarding.php supports loading plugins, content, and language packs. For the purposes of this article, I’m going to follow the content. It’s an array that might look like this:

return array(
	'content'      => array(
		'homepage' => array(
			'post_title'     => 'Homepage',
			'post_name'      => 'homepage-gutenberg',
			'post_content'   => require dirname( __FILE__ ) . '/import/content/homepage.php',
			'post_type'      => 'page',
			'post_status'    => 'publish',
			'page_template'  => 'page-templates/blocks.php',
			'comment_status' => 'closed',
			'ping_status'    => 'closed',

Let’s continue down the manufacturing line. That array of data gets sucked into Genesis’ onboarding.php into a variable called $config that’s tucked into a function called genesis_onboarding_content(). Here’s what that function looks like:

 * Returns an array of onboarding content provided by Genesis or the child theme.
 * @since 2.8.0
 * @return array
function genesis_onboarding_content() {

	$config_file = locate_template( '/config/onboarding.php' );

	if ( ! is_readable( $config_file ) ) {
		return array();

	$config = require $config_file;

	return isset( $config['content'] ) ? $config['content'] : array();

All that’s happened so far is that we’ve made the onboarding content from the child theme available to the Genesis Framework. It’s up to Genesis to use it.

Still with me?

Genesis uses it when it calls the genesis_onboarding_content() function from /lib/admin/onboarding/ajax-functions.php. That’s a new file added in Genesis 2.8.

If you look back to the previous code snippet, you can see that all the function does is return an array containing the content.

We’re still hanging out in ajax-functions.php.

$content = genesis_onboarding_content();

The value returned from the function is stuffed into a variable called $content. From there, that content is added to the database via wp_insert_post().

And, voila! A page is created in the user’s WordPress install that contains demo content.

What’s happening in the child theme onboarding file

So far, as the developer, all you’ve had to provide is a single file in a config folder: config/onboarding.php. Let’s unpack this file because that leads to the next steps of what else you need to include in your child theme files.

return array(
	'content'      => array(
		'homepage' => array(
			'post_title'     => 'Homepage',
			'post_name'      => 'homepage-gutenberg',
			'post_content'   => require dirname( __FILE__ ) . '/import/content/homepage.php',
			'post_type'      => 'page',
			'post_status'    => 'publish',
			'page_template'  => 'page-templates/blocks.php',
			'comment_status' => 'closed',
			'ping_status'    => 'closed',

The contents of this array are the parameters that get passed to wp_insert_post(). For the post_content, the theme goes hunting for /import/content/homepage.php (which subsequently references a couple of images also living in the /import/content/ folder). That file contains all the block markup that will become the post content for the Homepage. If you’ve ever worked with an XML import in WordPress, the concept is similar. You’ve got a file full of markup and that’s gonna get inserted as the post_content for that post entry in the database.

The next bit I want to point out is the page_template. That instructs the onboarding process to assign page-templates/blocks.php as the template for the Homepage. If you’ve ever created a custom template and assigned it to a page, that’s all that’s happening here.

Use a custom template

Create homepage.php

Step 1. Create a WordPress page

Are you ready to try this out? The first thing you’ll want to do is go create a page that you want to be your theme’s home page. Use the block editor. Make it beautiful.

Step 2. Grab the markup from that page

Once you’ve done that, the next step is to grab the block markup for that page. From the editor screen, click the three little dots in the upper right corner to open a menu. Change the Editor view from Visual Editor to Code Editor.

Select all of the markup from the Code Editor and copy it.

Block editor > code view
Step 3. Create a php file

Head over to your code editor and create a folder called /import/ in your child theme root and then create a file in that folder called homepage.php. While you don’t HAVE to use the same naming convention or file organization, I’d recommend following it unless you have a good reason not to.

The homepage.php file must return a string containing the content you wish to import (you know, the stuff hanging out on your clipboard right now).

Step 4. Follow the official instructions

The good people at StudioPress wrote up instructions on how to structure homepage.php and what all needs to be in that file. Follow the instructions!

Create the blocks template

If you’ve ever created a landing page template, the blocks template is similar in concept. While this template isn’t required, it’ll ensure your home page doesn’t look goofy. The blocks template is used to:

Here’s the template used for the block-based homepage on the Genesis Sample theme.

Put it all together

Whew. I think that’s the first time in a long time I’ve written a post that required me to use H5 headers. That was a lot.

My hope is that you now have a better understanding of how you can create a block-based homepage with WordPress 5.0+ (Gutenberg) and Genesis 2.8+. You’ve also learned that you can take it a step further by creating an onboarding sequence for your theme users that automatically generates the home page with pre-populated blocks.

Host your WordPress site with WP Engine and get Revolution Pro for free (and all the other StudioPress themes as well).

What do you want to learn next? Leave me a comment. πŸ™‚ For more resources on Genesis and Gutenberg, be sure to check out Bill Erickson’s blog.

28 thoughts on “An Introduction to Block-Based Homepages with Genesis Framework”

  1. This is wonderful!! I feel so much better about how the new onboarding is going to work. Very good explanation…I’m itching to try it out now lol.

  2. Carrie, this is an extremely helpful post, thank you so much!
    I’ll bookmark for reference in the future.

    Let me tell you my experience with widgeted homepages:

    I bought the Parallax Genesis child theme years ago, because that looked great. I was new to WP at that time.
    Then when I tried to customize the homepage days have passed with copying html code from draft Pages where I first had to figure out how it would look.
    Then again many hours with adjusting CSS.

    Also, had to add code to allow shortcodes, etc.

    I truly hated the process!

    Then at one point I got enough of the whole thing, and I just switched to the Genesis Sample theme, and just edited the homepage like it was any other page on the site.

    It was a wonderful experience πŸ™‚

    To make a full-width header I just widgetized the after_header area, and put some text with a great header image.
    Same for the before_footer.

    This way, the page content was inside the full-width image sections, and was super easy to edit.

    Here’s the site:

    And now with Gutenberg, it really got a lot more simple, thank God πŸ™‚
    Many people are against, but in my view, it was a really necessary step.

    Also, this “Blocks” page template is really helpful, I’m so happy that StudioPress are making these changes.

    1. Thank you for sharing your experience, Miklos! I think many have shared your same frustration trying to make home page customizations. Glad it’s getting to be a simpler experience!

  3. It’s so exciting. Can’t wait. Thank you again for being ahead of the curve and willing to share your experiences. [Also: I’m going to steal your yacht line. ]

    1. Thank you, Michael! I think they changed the file location. I noticed Revolution Pro follows the /page-template/blocks.php format and Genesis Sample was /template-blocks.php. I don’t think it matters which method you go with, but I’m glad they’re picking a consistent convention.

  4. First problem I ran into is a very simple one. Many designs I get involve segments with a full with background. When using Genesis Sample the content is limited to a certain width.
    So for a block, e.g. a H2 with full with solid color background the whole css has to be rigorously rewritten.

    I really think the modular blocks can be great for homepages, but then there must be an easy solution for the content blocks at full with.
    How would you go about that?

    1. You can make images go full width on any Gutenberg-optimized theme with the “cover image” or “full width image” blocks. As for content, why would you want that to go edge to edge? Seems like that could lead to a difficult reading experience on large monitors…

      1. Just curious, has anyone resolved the issue with full width images or cover image blocks not actually covering the full width of the screen?

  5. Hi All! Still looking for this solution for both sample theme and revolution pro. How do I widgetize areas of the page for the true full-width photos and content blocks? Do I need to create a new template? Instructions would be so helpful! Thanks! πŸ™‚

Leave a Comment

Your email address will not be published. Required fields are marked *

Carrie Dils uses Accessibility Checker to monitor our website's accessibility.