Adding Gutenberg support to WordPress theme

WordPress 5.0 shipped with a brand new, block-based content editor named Gutenberg. It is a huge improvement for content editing, and will become even more powerful as more blocks are built in core and in plugins.

All WordPress themes work with Gutenberg. It’s simply a new interface for creating content.  No changes are required to your theme to display your new block-based content.

However, there are some new features that your theme can take advantage of with minor updates. Also, the content editing experience can be improved with additional styling in the theme to ensure the backend block editor matches the frontend styling of the theme. 

I’ll guide you through updating your current WordPress theme to support these new features. If you’re not a developer and need help, I recommend you use Codeable – they are fast, knowledgeable, and affordable.

Developer's Guide to Gutenberg

I walk you through the technical details and code snippets you need as a WordPress developer building a Gutenberg website.

Read More

Frontend Styles

You likely have styles for many of these items (blockquotes, horizontal rules), but Gutenberg loads its own styles. You may need additional styles and specificity to ensure consistency.

Turn on wide images

Users can now have “wide” and “full” image alignments if your theme supports it. This allows the image to expand beyond the wrapping content area. You can see an example on my About page.

To add support, simply include this in your theme’s functions.php file:

add_theme_support( 'align-wide' );

It’s up to your theme to style these alignments. See my guide to wide and full image alignment in Gutenberg.

Blockquotes

Gutenberg includes two types of blockquote blocks: a standard blockquote and “large” one. It also includes a “pull quote” blockquote which is designed to be smaller and floated in the content.

All quotes can include a citation, using the <cite> element.

Here’s some base styling I use for these elements (using SASS):

/* Blockquote
--------------------------------------------- */
blockquote,
blockquote.wp-block-quote {
background: transparent;
text-align: left;
p {
font-size: 24px;
font-style: normal;
font-weight: 400;
}
cite,
.wp-block-quote__citation {
display: block;
font-size: 16px;
font-weight: 700;
margin-top: 12px;
text-transform: uppercase;
}
p:last-of-type {
margin-bottom: 0;
}
&.is-large,
&.is-style-large {
margin: calc( 2 * $block-margin ) auto;
p {
@include font-sizes( 24px, 36px );
}
}
}
/* Pull Quote
--------------------------------------------- */
.wp-block-pullquote {
border: none;
padding: 0;
blockquote {
border-left: 0;
border-top: 8px solid $highlight;
border-bottom: 8px solid $highlight;
padding: 16px 0;
text-align: center;
max-width: 50%;
margin: 0 auto;
}
&.alignleft,
&.alignright {
blockquote {
max-width: 100%;
}
}
}
view raw _blocks.scss hosted with ❤ by GitHub

Horizontal Rules

There’s a horizontal rule with its own class ( hr.wp-block-separator), so you should make that match your theme’s standard horizontal rule. There’s a few different styles of horizontal rules built into the editor: default, dots, and wide. Here’s the base SCSS I’m currently using:

/* Separator
--------------------------------------------- */
.wp-block-separator,
hr {
&:not(.is-style-dots) {
background-color: $border-color;
border: 0;
height: 1px;
}
&:not(.is-style-wide):not(.is-style-dots) {
width: 100%;
height: 4px;
background: transparent;
&::before {
content: '';
display: block;
height: 4px;
width: 40px;
background: $highlight;
}
}
&.is-style-dots:before {
color: $grey_9;
font-size: 18px;
letter-spacing: 12px;
padding-left: 12px;
}
}
view raw _blocks.scss hosted with ❤ by GitHub

Buttons

Gutenberg has a button block with its own default styling applied. You’ll likely want to customize this to match your theme’s button styles.

For more information, see my Guide to Color Palettes and Button Styling.

/* Button
--------------------------------------------- */
.wp-block-button {
.wp-block-button__link {
border-radius: 0;
font-weight: 700;
font-size: 16px;
line-height: 18px;
padding: 20px 24px;
&:hover {
background: darken( $highlight, 10% );
text-decoration: none;
}
}
}
view raw _blocks.scss hosted with ❤ by GitHub

Backend Styles

There are two ways you can add your theme styles to the Gutenberg block editor.

Option 1: Editor Styles

Your theme likely has editor styles added to make the classic editor more closely resemble the frontend. By default these are not loaded in Gutenberg, but you can turn it on.

WordPress is smart enough to automatically transform your styles so they only affect the block editor. With this approach, you can define a single set of styles that apply to both the classic and block editors. This is my preferred approach.

// Editor Styles
add_theme_support( 'editor-styles' );
add_editor_style( 'assets/css/editor-style.css' );

The add_theme_support( 'editor-styles' ); tells WordPress to load the editor styles in the Gutenberg block editor. Without this, they would only load in the classic editor (TinyMCE).

The second line, add_editor_style(), is the path to your editor stylesheet.

See my base theme as an example.

Option 2: Enqueue Block Editor Assets

You can enqueue your own styles & scripts in Gutenberg using the enqueue_block_editor_assets hook. This works the same as loading styles & scripts on the frontend using wp_enqueue_scripts.

Do not load your entire frontend stylesheet in Gutenberg. You should only load relevant styles, and prepend them all with the .editor-styles-wrapper class to ensure it only applies to the editor (not the WP backend menu, metaboxes…).

SASS

Whichever approach you choose, I recommend using SASS partials. This will let you write your styles once and compile them into both the frontend and block editor stylesheets as necessary.

Here’s my main.scss file, which generates the main css file on the frontend, and my editor-style.scss file, which generates a CSS file for loading in Gutenberg.

  • I’m only including relevant styles from the main stylesheet (style-guide and blocks)
  • I have a gutenberg partial for Gutenberg-specific styles – styles that shouldn’t appear on the frontend. I’m using this to “undo” certain styles Gutenberg adds to elements, so those elements match my frontend.
  • In the Gutenberg partial I’m setting the max width of blocks to match the site’s max width on the frontend ($content-width is defined in _base.scss)

Custom Blocks

While the core blocks are powerful, they may not serve all of your content creation needs, especially when it comes to complex pages like your homepage and landing pages.

Most of the sites I build include 6-12 custom blocks. You can build custom blocks with Advanced Custom Fields (my recommendation), or with JavaScript. You can also leverage block libraries like Atomic Blocks and Jetpack for additional block options.

Any more tips?

Do you have any recommendations for making custom themes more Gutenberg-ready?

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson

Comments

  1. Andy says

    This makes no sense, I built a theme from scratch today and Gutenberg blocks do not work. Surely you must include some CSS or Script for columns and layout blocks to work?

  2. Bruce 12:34PM L Chamoff says

    Bill, great article, but I am confused about one thing. You said in the last section:

    “But sometimes certain pages like the homepage and landing pages can be too complicated to rely on Gutenberg currently.

    My website is built 100% with Gutenberg – even the homepage uses the block editor. ”

    I feel like these two sentences contradict each other and just need clarify so I understand. In the first sentence, you said that certain pages like the home page are too complicated to rely on Gutenberg. Then, in the next sentence, you say that your home page does use it.

    So, my takeaway is although some home pages are too complicated for Gutenberg’s capabilities, you will found a way to use Gutenberg on your home page. Is that correct?

    • Bill Erickson says

      That’s a great point. I wrote this when Gutenberg just came out. At that point, we were using the block editor for standard posts and pages, and ACF for complex pages (homepage, landing pages).

      After working with Gutenberg for a few months, we shifted to building everything with the block editor. It’s now been years since I have built a page NOT using the block editor.

      For a more recent article on our design and development approach, see Gutenberg Theme Development.

  3. Bruce Chamoff says

    Good advice, Bill, and I am glad you are utilizing the block editor for everything now. I have been reading your articles for several years and am thinking of converting our podcast network to Gutenberg although I have been avoiding Gutenberg development for the past 2 years and just installed the classic editor plugin as well as added the hook to remove Gutenberg. Now it is time to refrain from doing that and force-feed myself the coding knowledge to build and style Gutenberg blocks. Currently, our podcast network uses ACF, but not the Gutenberg blocks from ACF, just the other types of custom field types.