Making sure your WordPress site is ready for Gutenberg when it goes live with WordPress 5.0 is extremely important.

This article is a guide for migrating your WordPress website from the classic editor experience to Gutenberg.

Gutenberg is nearly here! The massive editor overhaul for WordPress has been in the works for well over a year now, and we’re on the brink of release.

The new Gutenberg editing experience for WordPress will bring enhanced functionality, better content creation, and more of a page-builder style to the editor. It will also bring with it a host of challenges, mostly related to plugins that affect the editing experience.

Making sure your WordPress site is ready for Gutenberg when it goes live is extremely important. This article is a guide for migrating your WordPress website from the classic editor experience to Gutenberg.

In this article, we’ll cover:

  1. What Gutenberg is
  2. Whether or not you’ll be forced to use Gutenberg
  3. When Gutenberg will be live on WordPress sites
  4. Things you should be concerned about with the new editor
  5. What happens to existing content with Gutenberg
  6. The best way to prepare for migrating to Gutenberg
  7. Moving to Gutenberg on your live site

Let’s jump in!

If you

don’t have time to do the Gutenberg migration right now, click the button below to have the guide sent to you as an email:

PS! Bjork and I recorded a podcast episode all about Gutenberg and what it means for bloggers over on the Food Blogger Pro podcast. You can listen below!

What is Gutenberg?

Gutenberg is the newly reimagined editing experience for WordPress.

The current WordPress editing experience – the classic editor – is a big rich-text field. It’s kind of like a Word document – you can add paragraphs and images that all stack up on top of each other. If you’re fancy, you can also use plugins that make it possible to format the content into columns. Here’s a simple view of the classic editor:

The WordPress classic editor

Gutenberg lets you do everything that you can do in the classic editor – and then a lot more. Gutenberg rests on the foundational concept of blocks. In Gutenberg, everything is a block.

Paragraphs written in the content are blocks.

Images are blocks.

Recipes are blocks.

Here’s what that same post will look like in Gutenberg:

The WordPress Gutenberg editor

You’ll notice that there are some obvious visual differences. More whitespace, fewer formatting options (though they do still exist, they just only show up when you need them!), and the concept of blocks.

These blocks are the bread and butter – and also the awesome power – behind Gutenberg. Because everything is a block, extended functionality can easily be added to the WordPress editor, something that was difficult to do in the classic editor. Developers can create custom blocks for things like “quick tips” you add to your site, blocks for complex content like recipes, blocks for laying out your content into columns and rows.

The new Gutenberg editing experience is a really neat one that has the power to take your content creation to a new level.

While I could spend hours talking about everything each new type of block can do, that’s a bit beyond the scope of this article. if you want to learn more about how Gutenberg will change the way you publish, I recommend reading the official WordPress introduction to Gutenberg.

Will I be forced to use Gutenberg?

The short answer is that no, you can continue using the classic editor if you want. Gutenberg will be the default soon, though, so to continue using the classic editor you’ll have to install the Classic Editor plugin. This plugin will disable Gutenberg so that you can keep using the old editor you are comfortable with.

However, I really only recommend taking this route if you are certain that you can’t get your site Gutenberg-ready by the time WordPress 5.0 ships (see more on this below). By opting out of Gutenberg, you are forfeiting the awesome new functionality that comes with the new editor. Yes, it may take a couple of weeks to get used to, but once you spend the time to get to know Gutenberg, you’ll never look back.

When will Gutenberg go live?

Right now, you can download the Gutenberg plugin and give it a whirl. Since it’s not quite ready to go yet, it’s recommended to only use this plugin on development sites.

At the end of July 2018, WordPress 4.9.8 was released with a call-to-action to install and try out the new Gutenberg editing experience. After updating, you’ll see something like this:

You don’t technically have to take any action with that call-out, but it’ll be a good reminder that Gutenberg is coming and that you need to work to prepare your site for the update.

WordPress 5.0 will ship sometime in December 2018 or January 2019. This update will have Gutenberg included with Core. It will also activate Gutenberg as the default and only editor – unless you’ve installed the Classic Editor plugin mentioned previously.

What do I need to be concerned about with Gutenberg?

A shiny new editor that promises the world sounds awesome, right? So what’s the catch?

Gutenberg isn’t just some new tires and body paint put on the same ol’ editor. Instead, Gutenberg is a complete rebuild of the entire machine. Not only does it look and act different, it functions entirely different under the hood, too.

Plugins

This complete rebuild means that any plugins that affect the editing experience in WordPress will need to be extensively modified to work with Gutenberg.

According to the Gutenberg Compatibility Database (which was created by our lead developer, Daniel Bachhuber, but is no longer available), only ~16% of the plugins with active installs in the WordPress plugin repository can be considered “compatible” or “likely compatible.” That means that the other ~84% are either incompatible, or have yet to be tested for compatibility.

Because there is so much unknown when it comes to plugin compatibility, it’s extremely important to test all your plugins prior to activating Gutenberg on your live site.

Plugins that affect the editing experience – such as Tasty Recipes, Tasty Links, and Tasty Pins – will all need to be modified to function with Gutenberg. Plugins that don’t affect the editing experience, such as Akismet – likely won’t need huge changes, but they still need to be tested to make sure they don’t cause any unexpected problems.

Themes

Many basic themes won’t be an issue with Gutenberg compatibility. However, if your theme itself adds functionality to the editing experience (such as a built-in recipe card), then it, too, will need to be tested for compatibility with Gutenberg. This will likely happen as a by-product of testing your plugins, which we’ll discuss shortly.

What happens to existing content when I migrate to Gutenberg?

Great question! And fortunately, there’s good news.

All the content you currently have will be put into “HTML blocks” – blocks that (amazingly) contain HTML for your content.

That means that all your content will continue showing up just like it has in the past.

However, this doesn’t mean that you can just ignore this whole Gutenberg preparation deal. If you plan to create content moving forward, you’ll need to make sure your plugins and theme are all going to work with the new editing experience.

How do I prepare to migrate to Gutenberg?

As mentioned, migrating to Gutenberg isn’t quite a click-and-done thing. To continue publishing content as you have in the past, you’ll need to make sure that your theme and all your plugins will work with Gutenberg.

The best way test your website for compatibility is to install the Gutenberg plugin on a staging site.

If you’re now convinced that you need to test your site for Gutenberg compatibility, but you don’t have time right now, click the button below to have the guide sent to you as an email. Then take care of it when you’re ready!

1. Activate Gutenberg on a staging site

A staging site is a separate website that is an exact replica of your live site. Many hosts offer one-click staging sites that, with a click of a button, are automatically generated for you.

The beauty of a staging site is that it has all the plugins, themes, options, and content that you have on your live site. However, you can make changes to the staging site without worrying about causing problems on your live site.

Contact your host and ask if a staging environment is available for you to use. Chances are that they will have them available and can send you the documentation on how to get one up and running.

If your host doesn’t offer staging sites, you can try using the WP Staging plugin to get one up and running. If you’re going the plugin route, it’s a good idea to make sure you have a recent backup of your site just in case – we like to use VaultPress.

Once you have your staging site up and running, install and activate the Gutenberg plugin. Tada! Your staging site is now running Gutenberg.

2. Identify incompatible plugins

The next thing you’ll want to do is head on over to your plugins list and scan through them. Think about what each plugin does for your site and whether or not you interact with it when you’re using the editor.

Tasty Recipes, for instance, definitely functions inside the editor. While creating a post, you click the “Add Recipe” button and see a form pop up. You enter all the details into the form, then click “Save.” In the classic editor, Tasty Recipes then adds a shortcode to the post content with the recipe ID so that when the page renders the recipe can be displayed.

Akismet, on the other hand, doesn’t affect the editor at all. It simply scans comments as they come in and determines whether the content looks spammy or not.

Once you identify the plugins that affect the editor (write them down!), head on over to a new post. With the Gutenberg plugin installed, the new editor will be the default. Go to Posts, then click “Add New” or select “Gutenberg” from the drop-down:

Add new dropdown with Gutenberg highlighted

Wala! You’re now inside your first Gutenberg post. Pretty exciting, eh?

Like you saw before, it looks pretty darn different. If you just start typing, you’ll automatically create paragraph blocks. There’s no need to add a new block every time you want to add a paragraph – just hit the return/enter key.

A new gutenberg post

However, what we’re looking to do is to test the functionality of all the plugins we use that affect the editor. You’ll need to think about how you used that plugin in the past, then try to recreate that action in the new editor.

Let’s take a look at Tasty Recipes, for example. The classic editor had a button above the text area that said “Add Recipe.”

Tasty Recipes' Add Recipe button in the classic editor

In Gutenberg, that button doesn’t exist. In fact, that entire area is gone!

Instead, you’ll have to look through the blocks to find the functionality you’re searching for.

Click the “Add Block” button, then search for (or scroll through) to find the Tasty Recipe block.

Adding a Tasty Recipe block to a Gutenberg post

What if you don’t find the block you’re looking for?

If the block you’re looking for simply isn’t there, that means one of two things:

  1. The plugin author hasn’t made the necessary updates to register their functionality with the new editor, or
  2. The functionality doesn’t exist inside a block, but instead lives elsewhere (eg. Tasty Pins)

If you don’t find the block, make a note of which plugin you didn’t find and move on to the next plugin. We’ll discuss what needs to happen next in a bit.

The block is there! Now what?

Click it! See what happens. Attempt all the actions you’ve used in the past and make sure you can recreate those actions. If not, think about whether or not those actions are important to your site or if you can live without them.

For Tasty Recipes, When I add the block it opens up a modal window with the same form I’m used to filling out for adding recipes.

Modal form for filling out recipe details

When I click “Insert”, the recipe is added to the post just as I’d expect, minus some formatting issues.

Tasty Recipes display inside Gutenberg post

While formatting issues aren’t super ideal, those are easy for the plugin team to fix. The good thing is that all the complex functionality that I’d expect is there.

While testing your plugins, take note of any issues you come across – missing functionality, things that don’t work quite right, things that break other things. Spend a decent amount of time testing the plugins to make sure you’re not going to be losing any functionality that is important to your site.

Functionality that lives elsewhere

Tasty Pins functionality, for example, doesn’t live inside its own block. Instead, it lives inside the functionality of another block – the Image block, in this case. When you add an Image block, the regular WordPress media adder pops up and, if you have Tasty Pins installed, gives you a field to fill out the Pinterest Text. This text should then added to the image tag itself (see our blog post about WP Tasty plugin support for Gutenberg).

If a plugin doesn’t need a block, look for the functionality in other places you might expect it, such as:

  • Meta fields
  • Document settings
  • Images
  • Formatting options for other blocks
  • Settings for other blocks
  • etc

3. Contact plugin authors

If you identified a plugin that’s important to your site’s functioning but that doesn’t perform as expected (or at all), head on over to the plugin page on the WordPress.org plugin directory, or to the plugin’s website if it’s premium, and contact the support team. Here’s a sample email you could send:

Hi there,

I’m testing my site’s plugins and themes for compatibility with Gutenberg, the new WordPress editor. In my testing I noticed that {name of plugin} {describe what’s missing – isn’t available, is missing X feature, etc}.

Do you have plans to update {name of plugin} to work with Gutenberg? When can I expect these updates?

Thanks,

{Your Name}

Hopefully, you’ll hear back from the plugin authors that they’re working on an update. Also hopefully, that update will be available before Gutenberg is shipped into WordPress Core.

If you don’t hear back from the plugin authors, or if their timeline is too far out, then it might be time to find a new plugin.

4. Find new plugins

Take a look at all the plugins that you’ve identified to be incompatible with Gutenberg. If any of those plugins have functions that are necessary to the functioning of your site, it’s important to find an alternative that will work.

When looking for a new plugin, be sure to ask the support team if their plugin will support Gutenberg. If you can’t get a good answer, move on to the next one.

Once you’ve identified a good candidate, install it on your staging site and make sure everything works as expected and provides the functions you need.

Should I delete the old plugin?

This depends. If the old plugin still processes data for your old posts but you aren’t able to use it for your new posts then you may need to keep it installed. If the new plugin fully replaces the old plugin’s functionality entirely for old and new posts, you can delete the old one.

This is definitely something you should test on your staging site before going live with Gutenberg.

5. Preparing your live site for Gutenberg

Now you know all the plugins that work with Gutenberg and those that don’t. If a plugin doesn’t work, you’ve emailed the plugin authors to find out when support for Gutenberg will be pushed out. And if you didn’t hear from them, you found a replacement plugin.

Great!

Now it’s time to actually make the switch on your live site.

You can technically make all these changes on a development site and then push the new content to your live site. However, that’s a bit of a technical thing to do. If you work with a developer you could ask them about doing this for you.

However, if you’re taking care of this yourself you’ll just make the changes on your live site. You’ll start by adding all the plugins you need to replace ones that won’t work with Gutenberg. When that’s done, you’ll update to WordPress 5.0 when it’s available.

Make a backup

First things first, make a backup of your site. We use VaultPress to make daily, automated backups of our websites.

Our host also does daily backups – we like to have both, but if your host makes them then that might be sufficient.

Install new Gutenberg-friendly plugins

Once you’re sure you have a backup of your site, start replacing the old plugins that you’re certain won’t work with Gutenberg with the new plugins. As I mentioned, if the old plugin processes data for your old posts then you can leave it installed.

Moving to Gutenberg on your live site

You’ve now installed all the plugins that you need to function with Gutenberg. You know what to expect – which old plugins won’t work and which ones will – and you’ve talked to the plugin support teams about their Gutenberg support plans.

When WordPress 5.0 is released, Gutenberg will be the default editor.

If a plugin is very important to your site’s functioning and the plugin team said that support is coming soon, but not by the time WordPress 5.0 is released, then you may want to install the Classic Editor plugin and wait before activating Gutenberg on your site.

Once the important plugins have all been updated, you can delete the Classic Editor plugin and start using Gutenberg in all its glory. 🎉

And that’s it!

Moving to Gutenberg will probably take a couple hours of testing old plugins, emailing support teams, and finding new plugins. However, it’s something you’ll only have to do once, and it’s extremely important for your website.

The new Gutenberg editor is a big, awesome change for WordPress, and will be what WordPress developers focus on from here on out. If you stick with the classic editor forever you’ll be missing out on all the new features available today and all the new features and plugins available in the future.

Before moving to Gutenberg, it’s important to follow the steps in this guide to make sure that your existing setup will work with Gutenberg. If you’re lucky, no changes will need to be made and you can just sail on through the WordPress 5.0 update.

Good luck with the move to Gutenberg, and enjoy the awesome new editing experience!