Things to consider when updating a WordPress theme for Gutenberg

With Gutenberg getting close to being ready for a beta release and ultimately being merged into core WP, its API and patterns are at a level mature enough that theme authors (and theme shops!) can start planning ahead for the inevitable adoption of the new block system.

In this post we’ll see what the average theme author should have in mind when updating a theme for Gutenberg compatibility and ponder about the future in theme and plugin editing.

Backwards compatibility

First of all let’s dispel some myths or worries (if there are any left at this point). Gutenberg does not aim to break the web. It will indeed come with a grace period and be backwards compatible with “old school” WordPress. The Gutenberg FAQ is a great place to start reading about how this will work and the commitments the Gutenberg team has made in regards to it.

I’ll sum up a few key points (TL;DR):

• Existing post content will stay intact. The “Classic” block will offer an editing experience which is exactly the same as the one we have right now (with TinyMCE).
• The Classic Editor plugin will offer the choice of disabling Gutenberg until a theme can be 100% confident it’s ready. The Classic Editor plugin will eventually go away at some point but it’s not going to happen very soon.
• Custom field meta boxes will still work normally and be backwards compatible (more on that later on).
• Shortcodes will still work and be completely supported (more on that later on as well).
• There will be a big push for switching to block editing experience, and it’s not going to be a walk in the park for themes to fully embrace Gutenberg, but it’ll be worth it.

Ensuring Gutenberg compatibility

Although the above are comforting, Gutenberg will still need to properly be supported by any theme that’s worth its money. Based on our research, the effort required to make an older theme “Gutenberg-ready” will not be insignificant, but at the same time quite manageable. Right now, if someone was to enable Gutenberg on an existing website, nothing much would change. The content area would be replaced by the Classic block, all shortcodes and metaboxes would still work and there would possibly be minor styling issues on the admin side. (Your mileage of course may vary depending on what kind of customizations your theme comes with in its dashboard, meta boxes, and the editor). Note that the Classic block also offers the “convert to blocks” functionality which basically parses its content and actually converts each element in it (paragraphs, shortcodes, galleries, images etc) into different blocks. Anyone wishing to modernize their old content into blocks will be able to do so with the push of a button!

Styling themes for Gutenberg

One of the first things every author would want to do is make sure is that the default blocks look good on their theme. Thankfully, the native blocks don’t need styling like the native shortcodes did; every block comes with its own styles that ensure proper display. Extending a block’s appearance is left up to the author. For example some might want for specific blocks (e.g. the “Button” block) to better match their theme’s design. Gutenberg poses no complexities here, just an override in styles should do.

That said, there are a few opt-in features that Gutenberg cannot cover by default and themes might need to support, namely Wide and Full Width Alignment on images (and other blocks).

The two new alignment options (complementing Left, Center, and Right) are supposed to extend beyond the actual content width. As it’s easy to imagine, these options are very theme-specific and need to be applied on a per-theme basis by the theme developer if and when they makes sense. They are disabled by default and can be enabled by declaring support:

add_theme_support( 'align-wide' );

Once this feature is enabled two new buttons will appear in every block that supports alignment settings. The “Wide” option (supposed to expand the block a just a few pixels beyond the content’s boundaries) adds the .widealign CSS class on the block, and the “Full width” option (supposed to expand the block all the way to the viewport’s edges left and right) adds the .fullalign CSS class on the block.

That said, the actual usage of these two new alignment options are left up to the theme, as its the theme’s responsibility to provide styles for them (or even support them). For most themes which have a fixed, unremovable sidebar, the two options might not be wise to enable, but for themes providing fullwidth templates or dismissible sidebars it should be plausible.

Two good articles on how to start thinking about providing CSS support for these are the official Themeshaper blog post on styling themes for Gutenberg and Justin Tadlock’s post specifically about them as well as providing CSS techniques.

Other than that, Gutenberg also provides color palettes for blocks that allow color selections (again, the Button block for example). Themes can provide their own colors to be added in the palettes:

add_theme_support( 'editor-color-palette',
    '#a156b4',
    '#d0a5db',
    '#eee',
    '#444'
);

A good resource to bookmark and keep an eye on is the Theme Support section in Gutenberg’s handbook which is bound to be kept up to date as new opt-in features become available. For other inspiration, you can check out the three new Gutenberg-ready themes by the Themeshaper team (as also described in their blog post) Fashion Blog, Handicraft, and Ohana. These come with a set of adjusted front-end styles for Gutenberg plus editor styles which make the default blocks look and feel like the theme’s design in the post edit screen, a practice which some theme developers might want to follow for a more polished experience.

Shortcodes

We’ve concluded that shortcodes will still normally work in Gutenberg. The team has been working extensively to support them and Gutenberg already comes with a default shortcode block. However, blocks are meant to be the evolution of the shortcode as they make much more sense. Instead of having to type out code and look up parameters in documentations the user will get vastly a better interface for managing and previewing their content, while ending up with the same outcome on the front end as before.

As theme authors we should strive to upgrade our shortcodes into blocks and for this purpose the team has leveraged block transformations to make the upgrade process smoother. Assuming you’re willing to rewrite a shortcode into a block, you can define a block transformation which will allow a user to convert the legacy shortcode into its respective block with the click of a button, plus manage to automatically convert them on paste. Here’s a preview of how the automatic transforms will work on paste. Pretty nifty! The transformations API is not 100% stable yet (expect a tutorial when that happens) but you can see a rough example of how this is achieved here.

Custom Meta Boxes

After a lot of skepticism by the community the Gutenberg project has decided to provide full back-compat support for custom meta boxes. We’ve tested over a dozen of our themes that heavily rely on custom meta boxes and we’ve noticed only minor styling quirks. Out of the box Gutenberg will place your meta boxes into its own container so it’s expected for some meta box custom styling to break, especially if it was using removed parent selectors.

There are a few other ways that meta boxes could break, e.g. plugins that rely on the old editor’s selectors (e.g. post content, title fields or form elements inside it), plugins that leverage the TinyMCE API directly, etc. If you have really complex functionality in your meta box it will probably need some care. The team has provided failsafes and written up excellent documentation in the Gutenberg handbook on how to leverage them.

In short, we’ll be able to fall back to the Classic editor for meta boxes that are not Gutenberg ready and will definitely break:

add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
    null, 'normal', 'high',
    array(
        '__block_editor_compatible_meta_box' => false,
    )
);

The guideline is to optimally convert meta boxes into blocks (same idea as with shortcodes). Once we’d do that (if it’s an option) we could declare the metaboxes as backwards compatible only:

add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
    null, 'normal', 'high',
    array(
        '__back_compat_meta_box' => false,
    )
);

This will entirely hide the meta box from the user and will be loaded only for backwards compatible purposes (e.g. older WordPress versions).

Plugins, the customizer, and the future

Gutenberg came as a shock to most people when first announced, especially for popular page builder plugin authors and theme shops as it looks to be a monumental change with significant ripple effects to the way we’re used to work and the future of our products. However, as the team has already stated, it’s not meant to put anyone out of business; on the contrary, Gutenberg is WP’s evolution and a way for more business to be had for everyone. That said, the initial economic impact and transitional period will require significant effort from everyone. Page builders will need to adapt, custom meta box plugins (i.e. ACF) will have to be re-thought, upgraded, re-fitted, and all themes tested against a brand new editing paradigm.

As Gutenberg progresses from an advanced post editor to a full site building experience in the customizer over its next generations there will most probably be a lot more effort to be had although at the same time a lot of exciting new possibilities will emerge. It remains to be seen if the popular page builders will decide to build on top of  Gutenberg or continue on their separate paths and how a compelling premium Gutenberg site building experience will compete with the current status quo.

Regardless of any extra work, we’re personally very excited for Gutenberg and what it brings on the table for the WordPress community and its market. We’d be very interested in your thoughts on getting ready to upgrade your themes for Gutenberg, how are you preparing, and when do you think you’ll begin your testing. Let us know in the comments!