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-block-list__block 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)

Complex Templates

For modular templates that cannot be built with a single editor, I disable both Gutenberg and the classic editor, then build the editing screen with metaboxes.

I’ve found that Gutenberg drastically increases what we can build with the “standard” page template. Before Gutenberg, we would often build 5-8 custom page templates that required metaboxes. Now, almost all of these are built with Gutenberg.

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. 

For more advanced templates 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 a freelance WordPress developer and a contributing developer to the Genesis framework. For the past 14 years he has worked with attorneys, publishers, corporations, and non-profits, building custom websites tailored to their needs and goals.

Ready to upgrade your website?

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

Let's Talk

Reader Interactions

Comments

Leave A Reply