Learning Gutenberg: What is Gutenberg, Anyway?

Gutenberg is the new React-driven SPA editing experience in WordPress. Oh wait, a string of buzzwords doesn't count for a viable explanation of software? We’re going to unpack that string of buzzwords as we explain what Gutenberg is.

Article Series:

  1. Series Introduction
  2. What is Gutenberg, Anyway? (This Post)
  3. A Primer with create-guten-block
  4. Modern JavaScript Syntax
  5. React 101
  6. Setting up a Custom webpack
  7. A Custom "Card" Block

First, a before-and-after screenshot might drive home the idea for you:

On the left, the editor as it exists pre-Gutenberg. On the right, with Gutenberg enabled via plugin.

Buzzword #1: Editing Experience

Gutenberg is a redesign of the WordPress WYSIWYG editor.

The editor in WordPress has traditionally been that single WYSIWYG field, (the blob of content) that saves the entire content of the post to the post_content column in the wp_posts database table. Gutenberg doesn’t change this: it saves all the post content to the post_content table to be retrieved by calling the_content() in our PHP templates.

So yeah, Gutenberg is just a redesign of the editor... but it's a travesty to call Gutenberg just a redesign of the editor! It is so much more than that!

Gutenberg introduces an entirely new way of thinking about content in WordPress. It not only gives developers a native way to handle content in chunks (we’ll actually be referring to them as blocks, which is their official name), it enables end-users to create rich, dynamic page layouts with WordPress out of the box. Without Gutenberg, this would likely require a hoard of third-party plugins (read: shortcode vomit and server strain) as is currently the case with what will be known as the WordPress “Classic” editor.

For the purposes of this article and our learning, know this: Gutenberg does not change how WordPress functions at its very core. It is 99% a change to the editor's user interface. Hitting "Publish" still saves content to post_content—there's just a lot more opportunity to craft the user experience of writing and editing content.

Buzzword #2: SPA

Translation: Gutenberg is a Single Page Application within WordPress.

In a Single Page Application (SPA) an application runs on a single page load, and subsequent interactions are driven 100% by JavaScript and Ajax requests.

Note the "within WordPress' part of the above statement—Gutenberg does not (currently) impact any part of WordPress beyond where one would normally see the editor. In essence, Gutenberg replaces the WYSIWYG, TinyMCE editor with an SPA.

This means that writing content in Gutenberg is fast and satisfying, and I wish I could say my (limited) experience with developing blocks has been the same. For our journey, this SPA business means slow page loads during development (we are loading a lot of JavaScript), obscure and frustrating console errors, and npm modules for days.

Of course, that’s a glass-half-empty look at the situation. Glass half-full? It feels really good when something works. The wins are few and far between at first, but stick with it!

Buzzword #3: React-driven

Translation: Yes, Gutenberg is built in React. That’s probably not going to change anytime soon, if ever.

There was some #hotdrama back in September-October of 2017 about choosing a framework for WordPress since Facebook added a patent clause to React. But after major backlash from open source communities, including WordPress (which, ahem, powers ~30% of websites), Facebook changed it back.

As of January this year (2018) there were still whispers that a framework decision for core is pending, but until we get official word from the powers that be, let’s look at the facts.

  • Gutenberg is in active development.
  • Themes and plugins are in active development preparing for Gutenberg.
  • All of that is happening in React.

I’m putting my money on React, and if that changes, great! I’ll have React on my resume and get on to learning whatever its replacement may be.

Important Resources

  1. The GitHub repo — This is mainly for searching issues when they come up during development to see if they have already been filed.
  2. The Gutenberg Handbook — This is where the official Gutenberg documentation lives.


While the Gutenberg project is far enough along that there will not be any major infrastructural changes, we must remember that Gutenberg is brand new software in active development and anything could happen. Why not be on the front lines? This is exciting stuff.

The WordPress community has already begun to take up the task of creating tools, tutorials, case studies, courses, and community-contributed resources.

That being said, you may search a question that hasn’t been asked before. At some point, you will probably find yourself reading the Gutenberg source code for documentation, and you may find the existing documentation to be out of date. You may test out an example from a two-week-old tutorial only to find it uses a deprecated API method.

If you do come across something you feel is not as it should be, research and report the issue on GitHub, ask about it in the #core-editor channel of the WordPress Slack, or alert the author of the aforementioned out-of-date blog post. And if it’s documentation that’s a problem, you can always fix it yourself!

Setting Up

Now, I’d like for you to set up a development environment so that we can continue this discussion with more context. Do these things:

  1. Set up a local WordPress install, however you choose to do that—this can be an existing project, or a fresh install. Just something that can be very broken for demo purposes.
  2. Activate a relatively simple theme. Twenty Seventeen will work just fine. The only thing your theme needs to have is a call to the_content(); in its post and page templates, and most out-of-the-box themes do.
  3. Install Gutenberg. You can find it in the plugin repository. This version is quite far along and updated regularly, so we don’t need to worry about working from a development build.
  4. Activate the Gutenberg plugin and create a new post.

If you haven’t run a WordPress site locally before, check out this guide. We strongly recommend that you download something like MAMP, XAMPP, or similar if this is your first time.

Let's Explore

You should have something a lot like this:

A screenshot of a mostly blank post in Gutenberg with the title
A mostly blank post in Gutenberg. Typing / reveals the block selector.

As in the above image, typing a / reveals a list of blocks. Erase that / and on the right you should see a + that, when clicked, will reveal an additional listing of blocks, organized by category.

Screenshot of a blank Gutenberg post with a view of the blocks library
A different view of blocks, this time organized by category.

Notice the panel on the right with tabs for both "Document" and "Block." The "Block" tab is known as the block inspector, and gives us a nice area for block specific options like so, for the paragraph block:

A screenshot of a blank Gutenberg post with a graphic indicating the block inspector area on the right.
The block inspector reveals customization options for a specific block.

I recommend playing around with your post for a few more minutes and testing out the different types of blocks. Keep an eye on that inspector sidebar to see what customization options each block offers. All of these blocks you see now are included in a a library of core blocks and can be a reference point for creating custom blocks (which we will do in the next part of this series!).

After you’ve created a post populated with five-ish blocks of varying kinds, save and publish the post, then take a look at it from the front end. Nice!

Now, let’s do something crazy. Deactivate Gutenberg from the Plugins screen. Go back to the edit screen for that post, and you should see something like this, in the "Classic" editor:

Blocks, as they are saved in the database.

What are all these comments? Those are blocks! They map one to one with the blocks you chose when creating the post.

Under the hood, blocks are chunks of HTML identifiable by their surrounding HTML comments. In the example above, you’ll notice a few of the block names, i.e. wp:block-name are accompanied by JSON, such as the second paragraph block. When I specified some customization options in the block inspector, these were stored along with the block identifier so that now, when I reactivate Gutenberg, my settings won’t be lost; they are saved right alongside the block definition itself.

Before you reactivate the plugin, however, view the post again from the front end. Did you lose some styling? I did.

Go ahead and reactivate the Gutenberg plugin, and double check the editor to make sure your blocks are still intact. Because of those HTML comments, they should be!

Now, let’s poke around and see where these styles are coming from. When I inspect my paragraph block from the front end, I see a few inline styles—a result of options selected in the block inspector—as well as some structural styles from what appears to be a style.css file enqueued by the Gutenberg plugin (after 5.0 is released, remember, this will be just from WordPress, not a plugin).

A view of the style inspector showing a path to a stylesheet from the Gutenberg plugin folder
Inspecting the styles from the front end, we see there are styles coming from Gutenberg itself

Now, try inspecting that paragraph block from the editor view. You should see the same set of inline styles and the same p.has-background selector applied to the block from the editor view. Interesting!

This introduces the fact that blocks can have shared styles between the theme’s front-end and the editor. Pre-Gutenberg, we had theme, or front-end, styles, and we could separately enqueue an editor-style.css to add CSS to the WordPress admin area. Now, however, our blocks share styles between the front-end and the editor view pretty much by default.

Glass half-full perspective: this allows us to craft a content view for publishers that is much closer to what they will see on the front end. They will no longer need to hit the Preview button a dozen or more times to view small content changes before publishing.

Glass half-empty perspective: This could create more work for us—as designers and developers, we now have an editor experience to create in addition to the front-facing website! And we have to figure out which styles are shared between the two. However, I would argue that with a well thought-out design and front end strategy, this won’t be as much of an issue as you’d think.

Umm... Where's the JavaScript?

We’re going to need JavaScript to create a block in Gutenburg. So let’s make a block already! That's the focus of the next post in this series.

Article Series:

  1. Series Introduction
  2. What is Gutenberg, Anyway? (This Post)
  3. A Primer with create-guten-block
  4. Modern JavaScript Syntax
  5. React 101
  6. Setting up a Custom webpack
  7. A Custom "Card" Block