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.
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-widthis defined in _base.scss)
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.
Any more tips?
Do you have any recommendations for making custom themes more Gutenberg-ready?
Thanks for the straightforward explanation!
This is great, thank you.
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?
Bill Erickson says
WordPress core loads its own stylesheet for styling those elements. Here’s the block library styles on my site.
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.
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.