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.
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.
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
Here’s some base styling I use for these elements (using SASS):
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:
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.
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' );
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
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…).
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.
- 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-widthis defined in _base.scss)
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.
Any more tips?
Do you have any recommendations for making custom themes more Gutenberg-ready?