How to add WordPress Theme Styles to Gutenberg

I recented added Gutenberg styling to my latest WordPress theme Tabor. Here’s what went down and what I learned.

In the a couple months or so, Gutenberg will revolutionize WordPress publishing as we know it. It’ll finally bring a much-needed standardized content creation experience to WordPress. There’s just one small caveat.

Innovation simply can’t happen without WordPress theme developers committing to the Gutenberg experience. If Gutenberg will become the de facto editing experience for the average WordPress user, why not make it the best experience possible?

So after an inspiring trip to Nashville for WCUS, I decided to jump on the Gutenberg ship myself and start styling the upcoming editor within my latest WordPress theme, Tabor.

Here’s how it went, and what I learned along the way.

Adding WordPress theme styles to Gutenberg

If your WordPress theme does not properly support editor styling when WordPress 5.0 ships next year, it’ll be hopelessly dated as soon as Gutenberg launches. Even worse, your theme could cause a whole slew of styling issues within the new editor.

Adding WordPress theme styles to Gutenberg is not as “plug-and-play” as one would think. To start, you’ll want to enqueue a separate Gutenberg stylesheet using the enqueue_block_assets action.

Here’s an example of how I added Tabor’s theme styling to Gutenberg:

Apart from registering the Gutenberg-specific stylesheet, theme developers will absolutely need to fine-tune elements within the new editor to ensure that each displays with relative parity to the actual front-end output.

Otherwise, the editor won’t actually look like the front-end at all…

Fine-tuning theme styles within Gutenberg

The biggest issue is that block elements have margin and padding that simply do not exist within your theme’s front-end elements. Getting the editor styled “just right” will likely take a number of tweaks and wacky hacks.

I ended up prefacing nearly all of the custom theme styles with the .editor-visual-editor class within Tabor's Gutenberg stylesheet. Then I went in and started targeting the various textareas to try and get the editor as close as I could to the actual front-end output. 😅

Here’s a quick demo video of the results:

A short (and silent) video of Tabor’s Gutenberg support.

Unfortunately, without fine-tuning the theme styles within Gutenberg, you end up with a what-you-see-is-probably-close-enough-to-what-you-get experience. Not the promising editing experience you were hoping for.

Potential pitfalls

If your WordPress theme registers its entire front-end stylesheet for the Gutenberg editor, you’ll end up with a complete mess:

What happens if themes don't include styles correctly
What happens if themes don’t include styles correctly. ¯\(º_o)/¯

There’s quite a bit of work to be done for these WordPress themes. And from my experience reviewing WordPress themes at Envato — theme developers are notoriously lazy.

Sure, proper editor styles are required for themes uploaded to the WordPress repository, but outside of WordPress.org, it’s the wild west. So if your theme is doing it wrong — fix it now!

Closing

With the imminent release of Gutenberg, users will come to expect a true one-to-one content creation experience. If a WordPress theme’s editor styling isn’t up to par, the user’s experience is instantly disrupted. Then you’re missing the point of Gutenberg right off the bat: to capitalize on improving the user experience of WordPress editing.

Adding theme styles to Gutenberg is not difficult by any means. But it does take a bit of effort and consideration, to build a beautiful content editing experience on top of Gutenberg.

I encourage all theme developers to experiment with adding WordPress theme styles to Gutenberg. Let me know when you do, as I’m curating a collection of “actually” Gutenberg-ready WordPress themes — and I’d love to see yours!


Originally published at my personal blog on WordPress development.