How to Prepare Your Site for WordPress Gutenberg

Gutenberg is coming to WordPress soon. Is your website ready? While we still don't know exactly what form it will take, this new content system will be added to WordPress core in the future. Let's take a look at the potential impacts this could have on your site, and ways that you can determine, and fix, problem areas ahead of time.

What Is Gutenberg?

Gutenberg is a WordPress project that aims to give users more flexibility in the design of their content. Essentially, the project aims to replace the current editor, which performs mostly as a word processor, with a more visual and structured interface. Currently, Gutenberg is a plugin, and it grants users the ability to modify their content similarly to how Visual Composer or other drag-and-drop editors do—albeit in a simplified and highly intuitive way.

If you would like to  learn more about what Gutenberg is specifically, take a look at my earlier post "What Is WordPress Gutenberg?"

• 
  WordPress
  
  
  What Is WordPress Gutenberg?
  
  
  Kyle Speaker

The Pieces of Your Site

Gutenberg is a massive undertaking and will likely touch a large number of endpoints within your website. These are the three areas we'll be scouring for issues:

• Your Theme: Gutenberg comes with its own set of styles for content. Is your theme compatible? What will it look like with Gutenberg active?

• Your Plugins: It's possible that Gutenberg might interact with your other plugins in unexpected ways. We'll look at what those might be, and what to do about any issues that arise.

• Your Content: Gutenberg will affect how your content itself is displayed. We'll examine how that might change what your pages look like, and go over some potential fixes if you're having problems.

Setting Up a Testing Area

Before we get started, it's a good idea to set up a testing area where you can experiment with Gutenberg without breaking your live site. Ideally, you should set up your own testing area or create a local copy of your site. For more on how to perform either of those tasks, see the following tutorial:

• 
  WordPress
  
  
  Moving WordPress: Moving Your Site Manually
  
  
  Rachel McCollin

If neither of these is possible, you can do the testing directly on your site. Note that this can be risky, however, as we'll be activating and deactivating a number of pieces of your site. If you are doing the testing live, please make sure to create a backup of your site before beginning.

Once you know where you'll be testing, head to the plugins directory and find Gutenberg. Once it's installed and activated, read on.

Put Your Theme Through Its Paces

Now that you have Gutenberg installed, let's take a look at the first section of your site that might be affected: its theme. If there are already major problems at this point, such as database errors or problems with the WordPress admin, skip down to the What to Do When There Are Too Many Issues section.

Since Gutenberg interacts mainly with the content of the site, we only need to test a narrow set of things—luckily for us.

The first is that Gutenberg comes with its own style sheet and set of styles. Check each of the different page types and templates used on your site to make sure that they still appear appropriately. The main focus here is going to be elements within the main content area of your pages—especially content and image blocks. If you see any issues, it's likely that Gutenberg's styles are taking precedence over your site's.

To correct this, you'll need to identify where the problem is coming from. Typically, it will be a CSS selector focused on an HTML element, or it could be a priority of Gutenberg styles over your own classes. Whatever the case may be, try to identify where the error is occurring. Next, determine why the Gutenberg styles are overriding yours, and correct your code to allow it to take precedence.

Try to make any corrections within your own theme (or better yet, in a child theme or specified area for CSS in your theme), rather than altering Gutenberg. If you alter any of the files in Gutenberg directly, it's likely to be overwritten when the plugin is updated.

In a similar fashion, you'll want to give your admin area a once-over for any styling issues. Theme options and other custom-implemented sections generated by your theme appear to be the biggest culprits so far. Once you've identified styling issues in these areas, you can typically correct them by changing or creating a child theme and adjusting the CSS there.

Do Your Plugins Work?

After your theme is squared away, next up are your site's plugins. Specifically, keep an eye on any plugins that provide shortcodes that you use in your content (e.g. Gravity Forms), plugins that affect the appearance of your content (e.g. accessibility plugins that affect text size), and plugins that directly insert elements into your page (such as Advanced Custom Fields).

Looking at Shortcodes

To audit this area, first gather a list of any shortcodes that you may be using, along with what pages they exist on. With your list in hand, visit each of these pages to see if they are performing as intended. If you encounter any styling issues, then it’s likely that you're experiencing the same problem as above and need to readjust your styles.

However, if you're getting the dreaded rendered shortcode—that is to say that your page is displaying the [shortcode] instead of doing what it should—there is another solution. In this case, you can look at the block where the shortcode is and confirm that it’s not considered text (looking for and removing unwanted tags around the shortcode). If the problem still persists, moving the shortcode to a more appropriate block type should get everything back up and running.

Content Appearance

This issue arises from the same problem we've covered previously: style overrides. Identify the elements that are being affected and correct the CSS.

Element Creation

The final area that we'll be looking at for conflicting issues concerns element creation.  Any plugin that inserts HTML elements into a page without using shortcodes is suspect here—for example, when PHP pulls in custom fields from the Advanced Custom Fields plugin.

The most common slip-up with element creation revolves around blocks being mismatched. Since Gutenberg provides its own styles, there is a chance that if your elements are created inside an unintended block, they may render incorrectly. The fix for this is making sure your code adds elements to the block where you want them to be.

Is Your Content Appearing as Necessary?

This is not quite as urgent as the other problems we've discussed, but there might be some complications with how your content is rendered. Most of these problems will be from minor styling changes or how blocks are organized. To correct this, you'll have to play around with the block system until you get your page how you want it.

What to Do When There Are Too Many Issues

Did you run into a problem that you couldn't solve with the suggestions in this article? Don't panic! There’s still some time before Gutenberg hits WordPress Core.

First, record what the error is and what steps led to the error. The more information that you can gather, the better. Pass all of this information along to the Gutenberg team. With luck, they'll be able to determine the issue and fix it in a future release.

If you were working on a staging site, then at this point, that's all you can do for now. Continue to check the release notes to see if your problem is solved, or possibly work on solving it yourself.

If you were working on your live site, deactivating Gutenberg should put everything back to normal. If not, then now is the time to revert to that backup you made!

Good Luck on Your Install!

Gutenberg aims to be a massive change to the WordPress environment, one that looks to change content for the better. Before it hits the main branch, make sure to check that your site will function with the new changes. If you have problems other than what's listed here, better solutions, or corrections for anything in this article, please leave a comment below!