I migrated to WordPress Gutenberg and this is what I learned.

I migrated to WordPress Gutenberg and this is what I learned.

Gutenberg is the fifth incarnation of WordPress and presents a major shift for the platform. There’s been much noise and highly polarised views of the changes it represents. It went as far as prompting a rebellion that gave rise to the “ClassicPress” spin-off.

Over the past couple of weeks I’ve had the pleasure of working on some migrations that have involved large quantities of content. While I could have packaged this up as “advice” and sold it at vast sums as “consulting”, I prefer instead to offer some reflections, thoughts and ways I found round some of the problems I encountered.

It’s all about the editor

Ignore the hype and tech talk, for the average user Gutenberg is all about the editor. At first glance doesn’t appear that scary. It looks a lot like the old editor with its open expanse of white space waiting for your words, surrounded by menus and options. However, looks can be deceptive.

Whereas your old text editor just put text in a long line, the new one rips it up into “blocks”. Each paragraph, image, gallery and header becomes a “block” of a specific type. A small, self-contained piece of content, it has certain advantages, such as being able to reorder things easily or assign specific CSS classes to bits of text. There are also quite a few “quirks” that hit productivity badly.

Existing content (sort of) works

The most important “block” is Gutenberg’s “Classic Editor” that ensures backwards compatibility. In theory old content should render correctly through this and you should be able to update it. To a point that’s correct, although I found there were random occasions where it didn’t work that way, usually when shortcodes and plugins were involved.

The rule that seemed to work was if I had to inspect a post it was best converted to the new format (more on that in a minute).


I broke galleries

A couple of the sites I worked with had custom gallery plugins to match their art direction objectives. While existing galleries worked fine, new ones stopped working. Responses to bug reports suggested site owners were expected to create their own “blocks” and use those instead. This created a version control and maintenance issue as it would mean some pages would have galleries supported in one format, others in a different one. Make a change in the future and BOTH gallery approaches would have to be updated.

“Create a block” seemed to be a recurring theme. Aside from wasting money in having to cut code to duplicate something that already worked, it also created a maintenance issue. Old content used the old “plugin” approach, while new used “blocks”. Change the way “new” worked and “old” either fell out of step or needed updating too.

Living with this compromise is probably the way most will go, perhaps picking up and reworking old content when it needs updating. Alternatively, one site took the hit and spent a few days doing the work now and retiring their pre-block solution. The importance they placed on consistency of experience drove that decision.

Blocks are a pain

One of the neat things about “Classic WordPress” was it didn’t take a huge amount of JavaScript knowledge to put together a quick tool. There’s a few features on this site that use plugins I put together relatively quickly to generate HTML that was then styled with CSS. Blocks, however, seem hell-bent on  using JavaScript. WordPress is already “header heavy” if you leave it untouched, but with Blocks it becomes a joke.

How bad was it? When I was stuck on the Three network with poor mobile broadband I couldn’t load Gutenberg sites properly. Frustrating for a project team member, and an instant complaint for a customer.

Copy / Paste from Google Docs was erratic

There’s something about Google Docs that WordPress has never liked (at least not on Apple’s platforms). Paste text in from Pages or Word and the editor respects the end of paragraphs, displaying the clean line in the editor and the correct tags around it when the post is published. Google Docs doesn’t seem to work that way, so it needs a double line break to get it to recognise the paragraph.

On Classic WordPress it was easy enough to run through a post and edit it if someone forgot to add the double line break. Not so with Gutenberg. Multiple paragraphs can end up together in the same block (remember those). Sometimes I lost headers, sometimes paragraphs ran into one another. It all required manually editing and a bit of cut/paste as transforming snippets of text within a paragraph block isn’t supported.

Don’t use the editor as an editor

The biggest issue I found was when the editor was used as an editor. To be fair, this is not something I would ever suggest people do, but when migrating large quantities of content there is a temptation to dive in and make the changes there and then. While this was OK for small changes (like correcting spelling mistakes or removing people no longer at the company), for more involved changes and rewrites it’s a no-no for me.

Although it sounds less efficient, I found it more effective to take more substantial edits out of Gutenberg, run them through the usual editing process and then drop them back in.

Be patient

Gutenberg is a major change and it behaves differently in some places. Some frustration I came across was born from the conflict between expecting it to be “good old WordPress” and the new editor’s focus on blocks. Quite a bit of it was rightly placed at the door of the software’s developers.

It will take time to iron out the bugs and quirks, for plugin developers to catch up and a body of knowledge around “blocks” to form. There are a lot of people with big investments in WordPress, so these issues will be tackled either from within the product or by smart developers at the edges.

Last thought: treat it like a full migration

Either way, if you’ve not migrated to WordPress Gutenberg and you have a lot of content or rely on custom code and plugins, I strongly suggest holding off. Don’t treat this like a “one click” upgrade of software, but rather a migration to a new software platform. Run it through a test set-up somewhere, get your content reworked and tested, then import it into a fresh install.

This was by far the easiest way I came across to migrate as painlessly as possible for those who consume the content on a WordPress site.

About Ross A Hall

I help companies make the most of content. Some people call me a writer, others a content manager. I prefer "someone who gets results".

Need a hand? Get in touch.

  • twitter
  • pinterest
  • linkedin

The Collectors: an experiment in tour poster design

My name is Ross Hall and I am a Content Manager. This is what I do

Photographs from November: churches, boats and lights

Off-Page SEO. What it is and why it matters to your small business

How to use the skyscraper technique to boost your content marketing

What happened to the navigation?

The photographs of October: churches, houses and a castle

Document layouts: examples and concepts