The Secret Manual – Hidden Features and Gotchas in WordPress Gutenberg

For content creators, change in daily routine is fatal to productivity. This is especially true during the transition to Gutenberg since it still contains a few “gotchas” that may stymie people and interrupt workflow. I list a few here, along with some workarounds to assist users during active development. Gutenberg will be updated as soon as issues are resolved or refactored.

Now it’s one to the reason for this post: to alert content creators to the hidden features of Gutenberg that streamline writing workflow. As we all know, each time we learn a new software or tool we tend to judge it at our “beginners level”.  We may even throw in the towel before we reach mastery. And that applies to the current editor.

And if you depend on the website for your livelihood, I recommend creating a copy of your site on a staging site before upgrading to WordPress 5.0

This post assumes that you have already gotten your feet wet with Gutenberg and WordPress 5.x If you haven’t I suggest that you read one of these excellent resources under the Beginner’s Guides to Gutenberg

There is also a whole team working on an official user manual for the Block editor. Until that’s published, it’s all a bit fragmented. If you are a technical writer and would like to lend a hand, join the #docs channel on the WordPress Slack 

---

Table of Contents

Beginner’s Guides to Gutenberg

• WordPress.com User Guide
• WordPress.org User Documentation (work in progress)
• eBook by Modern Tribe:WordPress & Gutenberg
• Beginner’s Guide to Gutenberg by Mike McAllister
• GoGutenberg by WPSmackdown
• The Complete Anatomy Of The Gutenberg WordPress Editor by Manish Dudharejia in Smashing Magazine
• WordPress Gutenberg Guide by Marko Saric

Editing Permalinks

With Gutenberg 4.4 you can now edit the permalink in the document panel of the sidebar.

Once you save your draft, you can modify the permalink by clicking into the title section. There you will see the permalink editing space above the title. Developers and designers discuss on Github on how to improve this feature’s discoverability.

For users using an older version of Gutenberg on their sites (pre-4.4)

Please note that there is no permalink created for a new post until you have clicked Save draft at least once (Marius Jensen, Support Forum)

Slash Command to Trigger the Block Inserter

Probably the most useful tool hiding in Gutenberg is the Slash Command. It’s also my favorite.  Using slash command invokes the Block Inserter including its search, so you don’t need to interrupt your writing flow to hunt for your mouse to add a quote or a list via the keyboard.
Begin by starting a new line with Enter. Then hit the “/” key and start typing the name of the block. “/l” gives you the list as a choice. Selecting it and typing your first list item is really cool.  Or you could just use one of the keyboard shortcuts below

But “/” + i gives you an image block, “/”

The introduced keyboard shortcuts also allow for the following combination

⌥⌘T Insert a new block before the selected block(s).

⌥⌘Y Insert a new block after the selected block(s).

Customize Your Workspace

Since version 3.8 there are three features to customize your writing workspace. The Unified Toolbar, the Spotlight mode and the Fullscreen mode. You can use all three together or each one alone. Some people are a bit taken aback by everything’s being block, especially each paragraph. “Spotlight mode” helps with that.

Top Toolbar (former Unified Toolbar)

And it can seem awkward for each paragraph block to have its own formatting toolbar that pops up on hover and covers text above. The Gutenberg team implemented a solution for this called Top Toolbar – which was just renamed from ‘Unified Toolbar.’

Switch it on in the Editor Settings menu, and reach it via the ellipsis menu (3 dots) in the top right corner. The Block Options menu is also available from the toolbar on top of the screen.

Spotlight Mode

This process is refined by a “Spotlight Mode”. The editor grays out the canvas except for the block you are editing. It also delays the visual clues about separate blocks while in writing mode in the editor, making it less distracting.But that has the down-side of making the features for individual blocks even harder to discover. But you can easily switch it off again by returning to feature mode.  

Full Screen Mode

With 3.8, Gutenberg now also has a full screen mode  You can switch it on and pretty much remove the top admin toolbar as well as the left admin menu. Once you remove the editor sidebar, all that stays on your screen is the Top Unified Tool bar and your content.

Full Screen Mode, Spotlight Mode and Unified Toolbar.

Disable Publishing two-step 

I personally like the Publishing two-step process. As soon as I hit the publishing button, the post will automatically shared on various social networks (via JetPack or other RSS to Social integration.

The Publish Two-Step has saved me more times that I care to admit.

On the 2nd publishing step you will also find JetPack’s Publicize area to modify the post to the social networks connected. It’s actually on the second step so you might not want to remove it if you are using it.

You are able to switch that off using one of the two methods.

One way is under the “Editor Settings menu”, you open via the 3 dots in the top right corners.

Or you can also disable it the first time you see it happening in “Are you ready to publish?” Screen. On the bottom of the screen uncheck “Always show pre-publish checks”. And it won’t bother you again.

Keyboard Shortcuts

New line as command line

Gutenberg developers also introduced a new concept:  new line as your command line.

By hitting enter in a paragraph, you can write another line or execute a few shortcut commands:

• `/` slash command to insert a block
• `>` to start a quote directly,
• `##` to start a heading, (in a post’s body you start heading hierarchy i with <h2>)
• `1.` to start an ordered list (also ‘1)’ )
• `-` to start a list.
• Using backticks ` at the beginning or the end` of a string adds code formatting to your string. (the same key as the ~ key)

I also learned a few more very helpful shortcuts,

• ⇧⌥⌘M Switch between Visual Editor and Code Editor.
• ⌘K Convert the selected text into a link.
• ^⌥S Remove a link.

Since the focus is now on block based editing, I was surprised to notice that there is no keyboard shortcut to switch to HTML editing on the block level. And that is where I do most of my HTML tweaks. Turns one I am not alone. I filed a GitHub issue and it seems to be on the docket to be added.

More Keyboard Shortcuts can be accessed, via at the Editor Settings Menu

I apologize that the shortcuts are all in MAC notation. If you open the Gutenberg editor on your machine, you’ll be able to look up the shortcut combinations your specific operating system. 

Copy/Paste from Anywhere

Matt Mullenweg’s favorite hidden feature is the parser built into Gutenberg that allows for copy/paste of content from various tools, like Evernote, Google Docs, Microsoft Word, etc. Here is a little matrix on what works across the various platforms:

Reusable Blocks 

Reusable Blocks offer a whole new level of content development. With Gutenberg version 3.9, you can now save a combination of blocks as one reusable block,  which you can also export and import on other sites. Why is this a big deal?

For instance you can build landing pages with certain disclaimers, calls to action and campaigns. You can make the wording, the combination between heading, image or cover image and CTA button available to your users, for their use on their own posts and pages.

The new Gutenberg release also provides ways to manage your reusable blocks: You can delete them, export reusable blocks, and even import Gutenberg blocks from other sources.

There is a power feature for the Donate Now button: If its link changes, you need to change it on just one page, and that updates all other instances on your site.

In other words, reusable blocks are not templates. They are “content + design” blocks. And, if you need to change things in one spot, but don’t want to change other instances, you simply convert it to a standalone block before making the changes. Just use the “Convert to Standalone Block” link in the Block Options menu.

How to align an Image?

We often add an image to break up dense text in a long paragraph, and it must be aligned so the text wraps either left or right of the image.  

This may be the biggest transition hurdle for new Gutenberg users. I never found it easy in the old editor, and it’s still a bit quirky in the new editor.

But I am content to switch out one bad UI with the another bad UI. Coming from the early days of HTML coding, I know about the hazard of image floating n web design. So I don’t have high expectations and am happy that it works at all.  Resizing the image is easier but the default experience is still not great.

The biggest change is that just putting the cursor on the top of the paragraph where you want the image to align doesn’t work. You need to add the image block above the paragraph that will be aligned with the image.  

Follow these steps to align an image:

1. Use the “Inserter” above the pharagraph.
2. From the “Inserter” select “image block”.
3. Upload or select an item from the media library.
4. Use the left or right align button from the block toolbar.
5. Use the blue dot handles to resize the image.

Or you can drag and drop an image – again – above the paragraph, and align and resize it to fit.

How Gutenberg makes it much easier is that it’s truly WYSIWYG! You don’t have to switch from editing to preview to see if your image aligns well. You see it right in your editor.

There is a whole series of two blog post about this on WPTavern to solve one thing. A clearly Jeff Chandler didn’t have this secret manual:-) 

• Adding Aligned Images to Paragraphs in Gutenberg Is Not as Tough as I thought
• How to Add an Image to A Paragraph Block in Gutenberg

WooCommerce Products and Gutenberg

WooCommerce is still working with the current editor. The post type “product” will load the classic editor and the known admin screen.

When you want to add Products to your blog posts or create Landing pages, WooCommerce loaded blocks into your Post and page admin if you have the Block editor enabled.

Earlier this year, there was a test period, and since 3.4 it was reverted back to the classic editor. “Since WooCommerce is not optimised for the Gutenberg editor we’ve decided to keep the old editor for now so sites do not break when WordPress 5.0 is released. Products are not content focussed, so using Gutenberg with our meta box placed awkwardly at the bottom is not ideal.” Source: GitHub Issue #20201

WooCommerce’s plugin has four different product views, is a rudimentary Product view. Later in the year WooCommerce devs will refactor products using the Gutenberg framework and tools, they announced…

Job Thomas, Happiness Engineer posted a few notes regarding WooCommerce and WordPress 5.0 on the plugins support forum. That’s definitely a good space to watch for WooCommerce users.

PootlePress released their premium plugin Storefront Blocks. The various views in grids, sliders, masonry or carousels are very slick and impressive. Take a look for yourself.

Formatting Multiple Text Blocks

Highlighting a few paragraphs and making them bold or in italics doesn’t work yet, unless you use the Classic Editor block. It’s one block at a time. Note: There is a GitHub issue where the foundation of multiple block behavior is discussed. It is a prerequisite to something as simple as formatting a paragraph and a list in italics. Here is the feature discussion, if you want to chime in

Posts are now locked for other users

If you are working in a team of editors, you are familiar with the post lock feature in the current editor. If one of your peers is right now editing a post, you are not able to access it for editing; you have options for read only or to take over the post.

“Title” is not a block

It looks like a block, behaves like a block, but it’s not a block. The post title holds a lot of weight, especially in backwards compatibility,  plus in other places of WordPress for category pages, for the RSS feed, and many little things. Gutenberg is not modifying how the post title works.

White space around the editor

The editor is “opinionated” regarding the space it occupies. Depending on the size of the screen, you might find “too much” white space on the side of your content.

The opinion from the design is that there is an optimal width for reading on screen, and if the display space is larger it is much harder to keep track of the lines. It adheres to a max-width.

A few people mentioned this in the forums, and the team is giving it another review. (1483)

If you feel the same way when you look at your editing screen, you could use the plugin (???) To fix it for yourself.

Is your Editor window too small?

• Get the plugin Add Admin CSS  by @coffee2code https://nptp.us/2wuZWiL
• Go to Settings
• Copy/Paste:
  `.edit-post-visual-editor .editor-post-title__block,
  .edit-post-visual-editor .editor-block-list__block {
  max-width: 1024px;
  }`

Keep in mind though, that usability studies have shown that a content window is between  480 and 600 pixels. For easier reading it’s actually half the size. That’s BTW is helpful to have a graphic to the right for the first section of your blog post. That’s one aspect. The other is that with Gutenberg you are aiming at a 100% WYSIWYG. So what you see in the editor should be the same thing that is visible to your visitors on the front end. If you make the editor screen too wide, a few things will wrap differently for your visitors. Quite a few writers found this tip helpful.

Grammarly doesn’t work well

“Grammarly considers block a separate text box, meaning if you create a 25-paragraph post, you have 25 separate text boxes Grammarly is trying to check. This forced me to disable Grammarly on my site.” Jonathan Bailey in “WordPress’ Gutenberg: A Practical Review”

REST-API conflicts

Marius Jensen has published a few issues that he and his team of volunteer forum helpers identified. Quite a few of them have to do with another fairly new module that made it into Core recently, the REST-API. Gutenberg development is based heavily on the REST-API so during developing Gutenberg, the collaboration with the REST-API made it better as well. At the foundation of this, it’s a programming issue, but it will bubble up to become quirks a content creator will need to be aware of:

Categories and tags are not showing up

Some security related plugins may have disabled all, or parts of, the REST API. This is used by Gutenberg to fetch all the data used to display content in the editor, so if you are missing fields, check if you have a security plugin enabled.  If so, see if it has an option for the REST API.

Updating Failed Message

If you are receiving a Updating Failed message when trying to save a post or page, check if you are using the services provided by CloudFlare. We are currently working with them to address a problem which blocks the Gutenberg save function. A workaround is available while we find a solution to this.

Anti-Virus Software

It’s been reported that some antivirus software may also block REST API requests. So if your antivirus software offers an application firewall, this may prevent you from saving posts. We are looking into this.

Blank Editing Screen

Some users may experience a blank editing screen. If this happens, a first step to testing should be to just hit refresh in your browser. It may be a “race-condition” that we’ve identified and are working on fixing.

Changelog

• Jan 13, 2020 – Updated WooCommerce Section. A lot has changed this we published the first version of the post. That’s the only section that’s highly outdated.
• Mar 7: Added WordPress.org User Documentation links – work started during WordCamp Nordic Contributor Day
• Mar 6: Added WordPress.com User Guide to the Beginners Guide section
• Jan 15: Remove inline comment residue from editing process. Thank you to  Mario Neuhold‏ @mrioa for alerting me to the oversight.

• Dec 14: Removed the section: When will WordPredd 5.0 be released. WordPress 5.0 was released December 6th, followed by 5.0.1 on December 13 for security updates.
• Nov 16: added shout-out to today’s Live Q & A + Screenshot of Permalink editing in Document panel of the sidebar of the editor
  
• Nov 12: added link to WooCommerce Sticky Post on Plugins Forum page and fixed a few more typos. – bph
  

Related Posts

Talks at WordCamp US, Notes from the Community summit. A wishlist, reflections and a preview –Weekend Edition 266

Patterns, Block Styles and Slotfills—Weekend Edition #263

Share