Introduction
Recently WordPress.com (and WordPress in general) has started pushing the new Gutenberg editor. It uses a block based model instead of a traditional document centric one. This I don’t like but I also don’t mind. It’s a different way of composing and I can see the benefit. However, Gutenberg is not ready if you post source code and I do this a lot.
Posting source code used to be done using the [code] shortcode. It worked fine and allowed you to specify the langauge for syntax highlighting. WordPress would automatically handle everything and knows this text should be treated as pre-formatted, and it should leave and display unaltered.
Recently I tried to edit an existing post that uses the [code] shortcode in Gutenberg and it was a nightmare.
Gutenberg doesn’t understand the [code] shortcode
Let’s look at this post with a very small amount of code as an example. First thing to do is login and go to Blog Posts. Then click the post and have it open up in the new editor in visual mode (the default). This will create a “classic” block which is expected since this was a post written with the classic editor.
This is what the code section looked like:
Wow! Blank lines between every line. The < turned into an entity. Oh and the
[code] shortcode was part of the text! This is pre-formatted text and it
shouldn’t be altered just by opening it in the editor (I’m looking at you
<).
Okay. Maybe this is just an issue with how it’s being displayed. Let’s try changing this to the code editor… Extra blank lines and the entity are still there… Not good so far. Okay, maybe this is because it’s a classic block. Switch back to the visual editor, click the vertical .’s and choose “Convert to Blocks”. OMG it didn’t work and now it’s worse.
Gutenberg was able to determine the code section and converted it to a block. Also, it knows this is a shortcode and put it into a shortcode block. But now it’s removed indentation while keeping the extra blank lines and < entity. Apparently it doesn’t understand the [code] shortcode.
Fixing It
At this point I contacted WordPress.com support to figure out how to fix this. Thier solution was to view the post. Go into the editor to edit the post. Delete the code blocks. Finally copy and paste the code from viewing into a new code block in the editor.
Okay… Really!? Copy and paste all of the code in the post back into the post because the editor can’t understand the [code] shortcode! I will reiterate that shortcode is how you post code with the classic editor and is the instructions provided by WordPress on how to do it.
For this one post it’s annoying but not too onerous a workaround. However, I have some posts that have 15 or more code blocks. That’s a lot of copy and paste. Plus, an easy way to make a mistake and miss one of the blocks. A quick edit turns into a long, combersome process, with the potential to completely ruin a post. Now I have to keep copies of every single post in case it gets messed up in editing and I have to go back and edit again because the editor made changes when it shouldn’t (also suggested by WordPress support).
Lets just do their fix
Delete the shortcode block, add a code block, and copy paste the code from the original post.
This actually looks right. But there is no place in the block settings, on the right side bar, to set the language for syntax highlighting… I’ll get to that in a minute but first lets preview the code. So, click preview.
Better, the < isn’t an entity anymore, but there are still extra blank lines
between every line.
Syntax highlighting
I mentioned not being able to set the language for syntax highlighting and the preview didn’t have any highlighting. It’s not doing some kind of language auto detection.
I wrote a post with code and the Gutenberg editor (not yet published) and I swear I was able to have syntax highlighting. When I went to look at that post it was using a “custom html” block with [code] shortcodes. I guess that’s a solution. But still, I swear I had a post using a syntax highlighting code block.
Eventually I found the post (an old one I had edited a week or so ago). It has syntax highlighting so I went to edit it and look at the block.
Uh… What? I have a working code block which you now can’t choose from the existing blocks and an error/warning about the block being unavailable. Doing some research I found an open issue for the Gutenberg project which says they removed the syntax code block because they weren’t satisfied with it.
The post looks fine in the visual editor but when I go into the code editor, it changed everything into entities.
Great, once again I have broken posts. It looks right but it should be treating
code blocks like <pre> tags and not modifying the contents. I don’t know if
this is the same, can’t edit without mangling, issue since I’m using the editor
to look at the post. Or if it’s broken because the syntax highlighting block
was removed. Surprisingly the block still works when viewing the post and shows
syntax highlighted source code.
The big problem is editing EXISTING posts. You can’t open an existing post in the Gutenberg editor without it being mangled. Even when it was created using the Gutenberg editor in the first place.
Custom HTML blocks with [code] Shortcode
This doesn’t actually work either. I wrote another (not yet published) post using [code] shortcode in a custom HTML block. It looked fine in the visual Gutenberg editor. I switched to the code editor in Gutenberg and it still looks good. All formatting and characters were retained. Best of all, nothing was converted to entities. All of the text was left as is without being touched or modified in any way, which is fantastic!
Then I tried previewing the post. Everything that was previously being converted to an entity was missing. One of the code blocks had completely managed formatting. Again, it all looked good in the editor but not when actually viewing the post. So I left the editor and decided to open it again to see what’s going on. Sure enough everything that was missing had been stripped out.
Obviously this isn’t a solution.
Conclusion
If you open a classic post that has [code] shortcode with the Gutenberg editor, your code will be mangled. If you convert it to blocks, your code will get mangled even more. If you write a post using Gutenberg and use a code block your code might display properly but will still be mangled internally. If you try to use a custom html block with a [code] shortcode your code will be mangled.
At this point you pretty much have to use the classic editor and forgo Gutenberg in WordPress. Hopefully, this will all be addressed and syntax highlighting will be supported. Along with Gutenberg being able to open and convert classic posts without ruining code formatting. Hopefully, this all happens before Gutenberg is made the default editor.
As of right I’m very disappointed and unhappy that I’ve wasted a day struggling to get make small tweak to a post to basically end up back in the classic editor because you really can’t use Gutenberg as it is right now. On the bright side I got a new post out of it.
That is, until I clicked “Save Draft” and it kicked me back into the Gutenberg editor… And the frustration begins again to get posts working properly… Thankfully, this post doesn’t have any source code. However, kicking me into the Gutenberg editor randomly when saving a draft is getting quite annoying because I have to go back into the classic editor and fix all of my code when trying to write new posts or edit existing ones.