This morning I deployed the Gutenberg block editor, the upcoming block-based editor for WordPress core, on this blog — and guess what? My website didn’t implode and disappear into the abyss! While the migration was not completely clean cut, the operation was pretty smooth. Here’s what went down on my journey migrating richtabor.com to use the Gutenberg block editor.

Activating Gutenberg

When Gutenberg is first activated, all of your content within Gutenberg-enabled post types is put into one singular Classic Block. The idea here is that your content should be completely intact with Gutenberg enabled, replicating the old school visual editor we’re all pretty familiar with.

It’s then up to the end user to decide whether or not to convert the content within that singular Classic Block into separate blocks. I appreciate this cautious, yet rather smart approach, as it lets folks update each post to use the block editor individually. Obviously, splitting the Classic Block into individual blocks is what we want to do; otherwise, why use Gutenberg in the first place? So, I went through each of my articles here, converting each to a full Gutenberg implementation.

Block Migration Quirks

For the most part, content seemed to convert to blocks well — though I did run into a few minor quirks here and there.

1. Shortcodes

First, I found a few quirks with shortcodes that I currently deploy on my site, namely call to action and click to tweet shortcodes. Some of them didn’t convert to use the new shortcode block properly, while others did.

While the shortcodes still performed properly on the front end, the inconsistency within the block editor added a little doubt to whether or not they would—so I went in and removed the old shortcodes, then pasted them into the new Shortcode block.

2. Images & Image Captions

Throughout my blog, a number of my images have accompanying captions. I found that about 30% of my captioned images did not properly convert with the initial classic block conversion. I’m not sure why.

I had to go in and delete the odd caption shortcodes and add the caption text to the actual image. I also found that some left and right aligned images did not retain their image sizes. When/if you deploy Gutenberg, I highly recommend double-checking all your posts with images to ensure they’re properly displayed.

2. Video Embeds

Often I’ll add really short videos to highlight projects I’m working on. I found that most of my Vimeo embeds were converted to HTML Blocks with the embed script added.

I went in, deleted those various HTML Blocks and added the Vimeo Embed block with the Vimeo URL inserted. Now, my videos were rendering properly within the block editor.

3. GitHub Gists

I have been using the oEmbed Gist WordPress plugin to easily add GitHub gists to my posts, as embedded Gists do not render properly within WordPress. Unfortunately, the shortcodes rendered by oEmbed Gist were not converted to use Shortcode Block.

Instead, each oEmbed Gist shortcode was implemented with the core Embed Block, which also does not support embedding GitHub gists — at least within the block editor. On the front end however, the gists were in fact displaying properly. While this isn’t a huge issue, it does detract from the WYSIWYG facet of Gutenberg—and the work I’ve put in to have my WordPress theme, Tabor, emulate that front end styling within the editor. I saw this coming early on and actually started writing a Gutenberg block plugin to easily embed GitHub Gists.

Check this out:

I went to each post showcasing embedded gists and replaced the Embed Block with my new GitHub Gist Block. While the block is not quite ready for production yet, subscribe here and I’ll let know when it is.

Spoiler alert — it’s soon! I’ve released the GitHub Gist Block as part of my block plugin, CoBlocks today.

Closing

Admittedly, I do have a fair advantage over many folks who will be faced with the pending release of WordPress 5.0 and Gutenberg. I’m already quite familiar with the block editor: it’s features, strong suits, quirks and all. And as the developer of my blog’s WordPress theme, Tabor, I was able to push out hot fixes quite often as I ran into little issues here and there.

There are still a few minor oddities that I’m wrapping my head around, but for the most part — I’m enjoying writing my first official post in Gutenberg. In fact, this is the first post that I’ve written mostly within WordPress itself. My typical workflow consists of writing off-site in Ulysses, then adding it to the site. Gutenberg ups the content creation game quite a bit. And as I’m working on Writy, CoBlocks, and updating my WordPress theme catalog to support the Gutenberg block editor, what better way is there to learn the ropes than by using the software day-in and day-out? So, are you ready?