Building for the Gutenberg editor

I recently worked on a WordPress project that went all in on the Gutenberg editor. Since it has a bunch of (relatively) new concepts to wrap one’s head around, I’m jotting down all the things I googled and learned about, and maybe it could be helpful to others.

Long post ahead, but this is still not exhaustive and detailed. Features like Variations and Patterns aren’t here, since I didn’t use them. Here’s an outline:

1. Primer and caveats
2. Editing Reusable Blocks
3. Theming the block editor
4. Creating & removing Block Styles
5. Adding custom HTML & attributes
6. Defining starter content with Block Templates
7. Using ACF Pro to create custom blocks
8. Using blocks in Widgets
9. Hiding the Gutenberg editor programmatically
10. The Gutenberg experience so far

Blocks: primer and caveats

Unfamiliar with or recoiling at the thought of editing in Gutenberg? No judgment. (This site is still on the classic editor; I edit mostly in HTML.) But here’s the basic idea:

Everything is a Block.

It can be your “atomic”, indivisible HTML elements—such as paragraphs, lists, blockquotes, or headings. Or it can be more complex, nested, and custom—such as buttons, pullquotes, columns, or widgets.

Caveat 1: There are lots of default blocks, so that may feel overwhelming. You can disable the ones you don’t need.

Caveat 2: There are several ways to achieve a look with different combinations of blocks, and settings that appear inline and to the side, so that’s also intimidating. Try focusing on content editing before fiddling with the layout and style. There are also options for the editor to get out of your way.

Caveat 999: If all you need to do on WP is publish straightforward prose (or poetry!) with the occasional media content, you may not need to dig any deeper. (And you don’t really need to read the rest of this?)

I like Gutenberg’s writerly, typographic composition space. It can be a completely minimal, distraction-free experience. I just hope that it keeps streamlining so that you get faster the more you use it.

So what else can you do with it?

Editing Reusable Blocks

A block or group of blocks can be turned into a Reusable Block, so you Don’t Repeat Yourself (DRY). When you edit it, that change will be reflected everywhere else.

But clicking “Edit only lets you change its name. Actually updating the Reusable Block requires you to find the “Manage Reusable Blocks” link, which is located either in the block category or in the topmost, rightmost dropdown menu—the one with the 3-dot icon or vertical ellipse.

Notice that it queries blocks as a post type, and you could maybe add it to the admin menu if that helps make it more obvious.

Anyway, if want to use it more as a saved snippet you can change every time you call it, you can also select “Convert to Regular Block”. If you’ve used modern design software like Sketch / Figma / Adobe XD, think of it as “detaching” symbols or components. The Reusable Block remains intact while you override a copied version of it.

Theming the block editor

Gutenberg has an opinionated design different from the rest of the WordPress admin to get you into that writing zone, but it can also look more like the front-end design of your site: add CSS and JS via enqueue_block_editor_assets. (Side note: there’s also a way to do this with the classic editor.)

One issue here is since you’re probably using similar code for the blocks called in the editor and the site, you’ll want to optimize how that’s generated in your workflow, maybe with Sass imports or build pipelines.

Creating & removing Block Styles

Blocks can have variations called Styles, and you can define your own. For example, a Button can vary in borders and shadows. Like a lot of things with Gutenberg, defining these block styles can be done either client-side or server-side.

Unregistering block styles is similar, but do read up on the notes that are marked important.

(Client-side) “When unregistering a block style, there can be a race condition on which code runs first: registering the style, or unregistering the style. You want your unregister code to run last […]”

(Server-side) “The function does not unregister a style registered using client-side code. […]”

Adding custom HTML & attributes

…Can “break” blocks.

There are several ways to edit blocks in code: choose “Edit as HTML” in the block toolbar, or switch to Code Editor view. But not all HTML or attributes are “accepted” once you switch back to the Visual Editor.

Say you’re thinking of adding data- attributes or (gasp) inline styles. Or you’re thinking of doing more stuff with tabular data. You might get the message “This block contains unexpected or invalid content” and a prompt to “Resolve” or “Convert to HTML”.

You can choose to drop that code Gutenberg doesn’t like, or convert it into an HTML code block, which loses the WYSIWYG features.

Defining starter content with Block Templates

A blank screen can be liberating for some, but a huge roadblock for others. Especially if you want to guide a client on what goes into a page, you can create presets with Block Templates.

• You can set nested blocks;
• You can add default values or placeholder text;
• You can lock the template so no blocks can be added or removed.

If you’re creating a custom post type in code, you can also a block template to the initial declaration.

Using ACF Pro to create custom blocks

Reusable blocks are OK for static content, but I had a situation where I wanted the client to pick a post as featured content. I looked at 3rd-party blocks and widgets that could approximate this, but I wasn’t too happy with their interface experience, feature bloat, or output code.

Since I had used Advanced Custom Fields and its premium version prior to this, I was aware of its support for creating custom blocks. You can look at their docs, but I followed this guide more closely, which had concrete examples to follow. The high-level steps would be to:

1. Register custom block in your code;
2. Create custom block in ACF with the input fields you need;
3. Define how the block will be rendered with a block template file (or callback);
4. Define the block CSS & JS, if any.

You can also do this from scratch, but I’d rather not ;)

Using blocks in Widgets

WP is slowly moving towards Full Site Editing powered by Gutenberg, where everything can be Blocks in Block Areas. You can check out how this is progressing, but it’s a long way from production-ready.

In the project I worked on, there’s a call to action section after the main content of every page, before the footer area. Initially, I thought I could programmatically insert a reusable block with block templates.

This would’ve been fine for a few pages, but this specific project had hundreds of pages. If I changed my mind, there would be no quick way to undo that action short of querying the database.

Instead, I still created a reusable block to keep that Gutenberg editing experience, but decided to put it in a widget area with the help of Reusable Gutenberg Blocks Widget. (There’s an outdated plugin warning, but it seems to be working fine. There are similar plugins that do this now, too.)

Hiding the Gutenberg editor programmatically

This is the opposite of building for the editor, but in case you don’t need the editor at all, maybe for specific posts or pages where you use custom fields extensively, you can take it out. You can use the filter use_block_editor_for_post to do this. Note that this will revert to the “classic” interface and drop the Gutenberg look completely. Of course, there are also plugins to do this.

The Gutenberg experience so far

It’s a bit awkward to see how polarizing Gutenberg is, not to mention more serious issues it faces with accessibility.

I can understand the possible mismatched expectation for Gutenberg to be a freeform graphical interface or page builder (I don’t really use those builders, or go for overly complicated WP setups for that matter).

Theoretically it would be less of a struggle for designers & developers to digest the concept of blocks, because their work already deals with components. It’s also good to see an outline and hierarchy of content and navigate with that.

I guess there are things in the execution that are falling short, apart from having to embrace a major change and an unusual mental model: It could be having layout controls and formatting controls appearing in one place and getting overloaded from having to deal with both at the same time. Or it could be the weirdness when you click or move blocks, then not getting the behavior you expect.

I would also like a lot more keyboard shortcuts. More broadly speaking, it’s taking a while to reach the “flow state” of doing things effortlessly. Ultimately, your tools shouldn’t get in the way of getting your content out in the world, and this is a complex problem to solve.