Getting your theme ready for Gutenberg

In a few months, WordPress 5.0 will be released with a new editor, code-named Gutenberg. It will be a huge improvement for content editing, but it will require some work to ensure your theme takes full advantage of the new features.

If you’re building custom themes for clients, you should be adding Gutenberg support right now. You might not activate it for your client, but you should be testing your theme with Gutenberg.

Here are some quick tips to help you make the most of Gutenberg.

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 the theme to style these alignments on the frontend to ensure it works well with the theme. Here’s the base styling I use:

@media only screen and (min-width: 768px) {
.alignfull {
margin-left: calc(50% - 50vw);
margin-right: calc(50% - 50vw);
width: auto;
max-width: 1000%;
.alignwide {
margin-left: calc(25% - 25vw);
margin-right: calc(25% - 25vw);
width: auto;
max-width: 1000%;
.alignwide img,
.alignfull img {
display: block;
margin: 0 auto;
view raw style.css hosted with ❤ by GitHub


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. I use Better Blockquotes to add this to the current WordPress editor.

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

blockquote {
background: transparent;
margin: 0 0 $base-margin;
@include font-sizes( 18px, 19px, 22px );
font-style: italic;
padding: 0;
text-align: center;
cite {
display: block;
font-size: 18px;
margin-top: 17px;
p:last-of-type {
margin-bottom: 0;
&.is-large.wp-block-quote {
@include font-sizes( 22px, 26px, 32px );
margin: 0 0 $base-margin;
padding: 0;
cite {
text-align: center;
&.wp-block-pullquote {
border-top: 2px solid $base-color;
border-bottom: 2px solid $base-color;
padding: $base-margin 0;
view raw _style-guide.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.


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.

I have a blocks partial for all my block-specific styles.

.wp-block-button {
margin-bottom: $base-margin;
text-align: center;
.wp-block-button__link {
@extend %button;
view raw _blocks.scss hosted with ❤ by GitHub
%button {
background: $highlight;
border: none;
border-radius: 4px;
box-shadow: none;
color: $white;
cursor: pointer;
padding: 10px;
text-align: center;
text-decoration: none;
width: auto;
-webkit-appearance: none;
&:hover {
background-color: darken( $highlight, 10%);
color: $white;
text-decoration: none;
view raw _placeholders.scss hosted with ❤ by GitHub

Backend Styles

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 .edit-post-visual-editor class to ensure it only applies to the editor (not the WP backend menu, metaboxes…).

SASS comes in handy here. I break my main stylesheet into smaller partials, then generate a separate stylesheet for Gutenberg.

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

  • I’m only including relevant styles from the main stylesheet (style-guide, post elements, 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.
  • Everything is wrapped in .edit-post-visual-editor, limiting it to only the visual editor, and increasing specificity of my general styles so they overwrite Gutenberg ones.
  • I’m setting the max width of blocks to match the site’s max width on the frontend ($grid-max-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. This ensures a seamless transition when Gutenberg is released.

In the future it may be possible to build these pages with Gutenberg, but it’s not stable enough now to attempt. Block building is still difficult, and core features are still changing.

In the next six months, I expect ACF (or a plugin like it) to pivot to block building, providing the tools for developers to easily create the blocks they need for custom theme development with minimal time and a unified design.

Is Gutenberg ready for clients?

After you optimize your theme for Gutenberg, you could leave the plugin active so the client can use it.  I’m not using Gutenberg with clients yet. It has come a long way and is fun to use, but the UI needs some work and there are many outstanding issues.

When we get closer to the WP5.0 release, I’ll setup Gutenberg on our staging environments so clients can experiment with the new editor without affecting the production site’s content.

A Good Start

Gutenberg is still changing. The styles we create now might not perfectly align with the final release of Gutenberg. But by starting with a good base and structuring your theme to work well with Gutenberg from the start, you’ll only need minor changes to get it perfect.

Your clients will appreciate the effort future-proof their site, and you’ll minimize the amount of work you’ll need to do once Gutenberg is released.

Any more tips?

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

Receive New Posts by Email


  1. I just received my first request from a client asking that I do some testing to ensure the custom theme we developed for them is WP 5.0 / Gutenberg compatible. This post will form the basis of our action plan to set up a testing and validation process.

    Many thanks for this Bill. Well done.

  2. Great read. Found this particularly funny given the circumstances…

    “Clients will appreciate the effort to future-proof their site”

    Future-proof, at least until the next time WordPress decides to make breaking changes. 😉

    1. You could use anything you like. It’s expected that the .alignwide class be some amount wider than the content area, and I picked half the distance between the left/right edge of the screen and the content area.

      For the .alignfull class, the left/right margin of calc( 50% - 50vw) makes it expand the full width of the screen. Technically, it adds negative left/right margin equal to the space between the left/right side of the screen and the content area.

      For the .alignwide, I cut this in half. calc( 25% - 25vw) makes the image take up half the gap between the left/right side of the screen and the content area.

  3. Hey Bill, thanks, this is great stuff. I’ve made heavy use of ACF Pro in a theme I’m currently developing, mainly for the “flexible content” fields. I know you’ve worked with ACF Pro in the past, so thought I would ask: Do you know if Gutenberg “blocks” will allow me to completely move away from a plugin like ACF, giving me the ability to add my own custom “blocks” to do what “flexible content” field allow me to do? If so, I would love to start transitioning completely away from using a plugin like ACF Pro or CMB2. Hoping this isn’t too specific a question for this post. Thanks!

    1. While it’s theoretically possible, it would likely require orders of magnitude more time to build (think 10-100x the time you spend with ACF). A better comparison would be building your own custom metabox with its flexible content field from scratch, except you’re doing it in JavaScript, a language with which you might not be as familiar.

      I think most developers will use ACF or a similar plugin to create custom blocks, in the same way you use ACF now to create custom metaboxes. For now, I’m still using custom metaboxes for complex pages like this and disabling Gutenberg just on those templates.

Leave a comment