Unblocking the Wordpress Block Editor

If you’ve read my previous blogs, you know I enjoy deep dives into non-intuitive user interfaces—Discord, GarageBand, and Google Docs, to name a few. Documenting these beasts comes with some peril. Software is mutable. After I post my detailed description of (fill-in-the-complicated-app-of-your-choice), a new improved version of the software renders my article obsolete.

Take Wordpress, for example. Five years ago, I wrote a blog about setting up your own Wordpress site from scratch using Wordpress v4.9.5. Six months later, the release of Wordpress v5 included a redesigned editor, called Gutenberg, and my blog contained not one shred of information about it. (To be fair, there wasn’t much I could say, as the new editor lacked basic accessibility. But I still felt like I’d created a blog that was almost instantly outdated.)

Today, Gutenberg is stable and accessible. I’ve been using it to create and modify Wordpress web pages for several months. The interface feels strange and awkward—an unavoidable consequence of accessibility as an afterthought, and a VoiceOver issue with lagging focus requires some finesse to work around. Nonetheless, it’s time to document this important Wordpress feature.

If you’re not a Wordpress admin or contributor—lucky you! Read no further. You will never need to use the Wordpress Gutenberg editor.

The rest of us must learn it. Once we do, Gutenberg has many benefits.

• Gutenberg makes it easier to design and maintain complex web page layouts.
• Using the current technology gives me a shared vocabulary with fellow Wordpress developers.
• Wordpress sites run more efficiently with fewer plugins. Switching to Gutenberg removes the need for the Classic Editor plugin.
• I co-admin with a sighted colleague. Using Gutenberg ensures our content is edited and maintained consistently.

This blog uses the following terms.

• Gutenberg. I use this term to refer to the editing feature in totem.
• Visual editor. This is Gutenberg’s default editing mode, which presents web page contents as a hierarchy of blocks that you can manipulate and edit. It’s commonly referred to as the block editor. In fact, I call it that in the title. But VoiceOver and official Wordpress documentation refer to it as the visual editor, so that’s what I’m sticking with.
• Code editor. You might have heard this referred to as the HTML editor.

This blog covers using Gutenberg with VoiceOver and Safari on a Mac. Wordpress, Safari, and Mac OS are under constant development. I tested the following versions.

• Wordpress version 6.2.2
• Safari version 16.4
• Mac OS Ventura 13.3

The Editor Layout

Let’s explore the layout of the editor page. Use your Wordpress admin backend to create a new page or post. This opens the editor, but be patient—in my experience, Gutenberg opens abnormally slow.

The Gutenberg editor page contains five regions. Press Control+Accent or Control+Shift+Accent to move between them. (On most English keyboards, the Accent key is above Tab and to the left of the numeral 1 key.) Another way to move between regions is to press VO+U and arrow to the Landmarks menu.

Here are the regions.

• Editor Content Region, the main editing window. This is where I do the bulk of my work.
• Editor Settings Region, with familiar controls for featured Image, Discussion, page attributes, and Layout.
• Editor Publish Region, with controls for publishing.
• Editor Footer Region, containing a breadcrumb in the block hierarchy.
• Editor Top Bar Region, with many controls including Preview and Save Draft.

What’s missing? Gutenberg removed the Wordpress administration sidebar. To access it, you must exit Gutenberg. Navigate to the editor top bar, Save Draft if necessary, then select View Pages or View Posts. This returns you to the familiar administrator backend.

A Quick Solution

I’ve always preferred a local editor for developing new posts or pages. A local editor allows me to add links and italics, spell check, and make revisions in an environment that I’m already familiar with. This isn’t a blind thing. The Wordpress visual editor is primarily a layout tool, and even sighted users don’t want to use it for content creation.

Fortunately, the visual editor supports locally created content. Create your content in your favorite local editor. Use the first line for your page or post title heading. Add bullet lists, links, and any formatting such as italics or bold. Do not use blank lines between paragraphs. Spell check, revise, and edit as needed. When your content is ready, do the following.

1. Select all and copy your page or post content (Command+A, Command+C).
2. Open Wordpress and create a new page or post. When the visual editor opens, VoiceOver focus is in the title heading block.
3. Press Command+V to paste your page or post. The first line of your content will become the page or post title heading. The visual editor will automatically create paragraph blocks as-needed for the remaining content.
4. In the Editor Top Bar Region, preview your page using the Preview menu, and in the Editor Publish region, open the Publish Panel to publish your page.

This workflow minimizes interactions with the visual editor and handles most of what I need to do in Wordpress. However, I still have occasion to edit existing content and create more elaborate block layouts, and both of those situations require a more in-depth knowledge of the visual editor interface.

The Slower Solution

The slower method is to enter your content a block at a time, setting the type for each block and entering its content as you go. To do this, you’ll need to be proficient at navigating around the blocks, editing a block’s contents and settings, and creating new blocks.

Navigating Around the Blocks

The visual editor has two main modes. Use navigation mode to navigate between blocks, and use edit mode to modify the contents of a block.

To explore navigation mode, open existing content in the visual editor. Move focus to editor content with Control+Accent, then press Tab until you hear VoiceOver announce the following.

You are currently in navigation mode. Navigate blocks using the Tab key and Arrow keys. Use Left and Right Arrow keys to move between nesting levels. To exit navigation mode and edit the selected block, press Enter.

That’s quite a mouthful, but let’s practice what VoiceOver preaches. Tab and Shift+Tab navigate between blocks. You can also use the Up and Down Arrow Keys.

Blocks can appear within other blocks. Left and Right Arrows navigate within the block hierarchy. For example, lists are stored in list blocks. With focus on a list block, navigate to the individual list items with Right Arrow. Up and Down Arrow will move focus through each list item. Left Arrow returns focus to the top-level list block.

Some things to note:

• VoiceOver focus sometimes lags while navigating between blocks. This issue makes it difficult to know which block has focus. Use VO+F3 to describe the item in the VoiceOver cursor, such as Paragraph Block, Row 4. You may need to press it multiple times while VoiceOver focus catches up.
• It’s easy to inadvertently Tab or Shift+Tab out of the editor and move focus to other regions. Use Shift+Tab or Tab to reverse into the Editor Content region, or if you’re totally lost, use Control+Accent.

Here are some other things you might want to do in navigation mode.

• Backspace deletes the current block.
• Command+Shift+D duplicates the current block.
• Option+Command+T inserts a block before the current block.
• Option+Command+Y inserts a block after the current block.
• Option+Command+Shift+T moves the current block up.
• Option+Command+Shift+Y moves the current block down.

You can undo any of these actions with Command+Z.

Editing a Text Block

To edit a block, navigate to it, then press Enter. VoiceOver will announce the following.

You are currently in edit mode. To return to the navigation mode, press Escape.

That’s good information. Enter puts you in edit mode, and Escape takes you back to navigation mode.

Recall, if you will, the classic Wordpress editor. It featured the following:

• An editor window where you could add, delete, and modify content.
• A bar of controls for features like bold, italic, link, indent, etc.
• A settings panel on the right side of the screen.

Once I realized that the visual editor presents a comparable layout in edit mode, Gutenberg became much easier for me to use.

Focus is initially in the block content area. For text-based blocks, this is where you add, delete, or modify text content.

Press Shift+Tab to move to the action menu, then use Left and Right Arrow keys to access options. For text-based blocks, this is where you set indentation, add links, and specify bold and italic. The controls vary by block type. Most block action menus contain controls to move the block up or down and change the block type. Press Tab to leave the action menu and return to the block content.

The classic editor settings panel controlled global page appearance. In the visual editor, use Control+Accent to access the Editor Settings region. A toggle button switches between the familiar global page settings and more advanced block-specific controls.

When working with the block content area of a paragraph block or any other text-based block, common text editing keystrokes and shortcuts work as expected. However, keep the following in mind.

• Enter creates a new block.
• At the end of text, Delete joins the current block with the following block.
• Likewise, at the beginning of text, Backspace joins the current block with the preceding block. (Be careful. If not in edit mode, Backspace will delete the entire block.)
• Arrow keys move between blocks. This feature makes blocks less of an impediment for editing. You simply have to ignore VoiceOver announcing each block as you arrow into it.

When done editing, press Escape to return to navigation mode. This should leave focus on the block you just exited. In practice, VoiceOver focus often jumps back to the first block. This is an annoying issue, and I don’t know of a workaround.

Copying and Pasting Blocks

Copying and pasting blocks is possible, but not in navigation mode.

To copy a block, navigate to the block, press Enter for edit mode, and press Command+C to copy.

To paste a block, press Escape to return to navigation mode, navigate to the block before the destination, press Enter for edit mode, and press Command+V to paste.

I would be hard-pressed to conceive of a more awkward copy/paste solution. Unless you’re copying and pasting between pages, it’s probably easier to move blocks up and down using Option+Command+Shift+T and Option+Command+Shift+Y.

Creating New Blocks

In navigation mode, create new blocks with the following keyboard shortcuts.

• Option+Command+T inserts a block before the current block.
• Option+Command+Y inserts a block after the current block.

In edit mode, while editing most text content blocks including heading blocks, press Enter to insert a new block after the current block.

The default new block type is paragraph. Press the forward slash key to change the block type. For example, after entering some paragraphs of text, you might want to create a heading block for the next section of text. Press Enter to create a new block. VoiceOver will announce the following.

Empty block; start writing or type forward slash to choose a block 

Thank you, VoiceOver. Press forward slash to open the menu of block types. Arrow down to Heading and press Enter. VoiceOver doesn’t acknowledge that the menu has closed or that the block type has changed. To confirm the block type, press Escape to return to navigation mode and VoiceOver will announce the block type.

To set the heading level, return to edit mode. Move focus to the block action menu with Shift+Tab. Arrow to the Change Heading Level button, select it, and arrow down to select the desired heading level.

Quick Formatting Text

While editing a text block, select text as usual and format text using shortcuts you’re already familiar with. For example, italicize text with Command+I.

Use the Command+K shortcut to quickly add a link to the selected anchor text. Note that this opens a dialog, and the link entry text field has a suggestion menu, but you can safely ignore this. For example:

1. Select the desired anchor text.
2. Press Command+K.
3. Type http://applevis.com. As you do so, ignore VoiceOver announcing suggested URLs.
4. Press Enter.

Putting it All Together

All this might seem a little overwhelming. To be fair, the first few times you use the visual editor, you will feel lost. Don’t be discouraged. With practice, the visual editor becomes easier to use.

Here’s a small example to help get your feet wet. Assume you want to create a simple page consisting of a title, a block of introductory text, a heading, and a final paragraph of text. How would you create that a block at a time? Follow these steps.

1. In your admin backend, create a new page or post.
2. When Gutenberg opens, it’s already in the visual editor, with focus in the title block.
3. Type the title text and press Enter.
4. This opens a second block, and it’s a paragraph block by default. Enter the introductory paragraph text, then press Enter.
5. This opens a third block, but we want a heading here, not another paragraph. Press Forward Slash. Arrow down the menu to Heading and press Enter. Enter the heading text, then press Enter.
6. This opens a fourth block, again it’s a paragraph block by default. Go ahead and enter the final paragraph text.
7. Press Escape to leave edit mode and enter navigation mode. Use Tab and Shift+Tab to move between the blocks and review their content.
8. To preview the page as it will actually appear to end users, Control+Accent to the Editor Top Bar. VO+Right Arrow to Preview. It’s a menu, so when you open it, you’ll need to VO+Right Arrow to select Preview In A New Tab.
9. After previewing, close the preview window to return to the editor. Control+Accent to the Editor Publish region to publish your page.

This is not a contrived example. I recently performed these exact steps to create a new web page for a site I manage.

Shortcodes

If you need to add shortcode to a web page, create a new block and paste in the shortcode. The visual editor automatically changes the block type from paragraph to shortcode.

Images

I bet you’d like to create an image block and make it display an image from your media library. I’ll leave this as an exercise to the reader, but feel free to post a comment if you get stuck.

When working with images, it’s my experience that I need to do much more than simply add it to an image block. I often need to identify which of possibly dozens of images to use, and crop and size the image appropriately. Gutenberg provides no tools to make this accessible. If your website makes heavy use of images, most blind admins will require sighted assistance.

A Word About the Code Editor

In addition to the visual editor, Gutenberg also supports a code editor for manipulating raw HTML. Use Command+Shift+Option+M to toggle between the visual and code editors. The editor page layout is the same as for the visual editor, but the code Editor Content region allows you to edit your web page HTML directly.

I use the code editor to make small changes. For example, the code editor is ideal for quickly fixing small typos or changing a URL or image file name. For changes that rearrange blocks, I stick with the visual editor. This avoids inadvertently disrupting the structure of the underlying HTML—and keeps relations friendly between myself and my sighted co-admin.

Wish List

If a genie granted me three Wordpress accessibility wishes, I know what I’d wish for.

1. In navigation mode, when using Tab and Shift+Tab to move between blocks, I wish VoiceOver’s focus didn’t lag.
2. When I press Escape to leave edit mode and return to navigation mode, I wish focus would stay on the current block rather than jump to the first block.
3. I wish I could cut and paste blocks in navigation mode. Having to switch between navigation and edit mode makes this operation tedious and time-consuming.

I’d also like a single keypress that would announce the current mode and location, but—dang it!—genies only grant three wishes. I’ll have to get by with VO+F3 and the Escape key.

Despite these issues, once you spend some time using Gutenberg, you might discover you prefer it to the Wordpress Classic Editor.

Summary

I don’t claim to be an expert on the visual editor, but I’ve covered everything I know how to do.

In the Gutenberg editor window:

• Move between regions with Control+Accent and Control+Shift+Accent.
• Toggle between the visual and code editor with Command+Shift+Option+M.

In the Editor Content region, using the visual editor:

• Quickly create several blocks by pasting content from a rich text editor.
• Navigate between blocks with Tab and Shift+Tab. Work around VoiceOver’s focus lag using VO+F3 to confirm the block with focus.
• Press Escape for navigation mode and Enter to edit the selected block.
• In edit mode, move to the action menu with Shift+Tab. Return to the block content with Tab.
• Use keyboard shortcuts to duplicate blocks, delete blocks, move individual blocks up and down, and insert new blocks before and after the current block.
• Change a paragraph block to anything else by pressing Forward Slash.

And in the code editor:

• Edit HTML directly for changes that don’t affect block structure.

Conclusion

This blog doesn’t describe different block types in detail. However, such information is widely available. With this blog as a starting point and some information gleaned from the web, most other blocks should be useable.

In the comments, I hope others will share their tips and tricks for using the visual editor.

Help me keep this information correct and up-to-date. If you spot a mistake, post a comment, and I’ll try to correct it.

If you use Wordpress as infrequently as me, Gutenberg’s palette of ad hoc keyboard shortcuts will be impossible to memorize. Referring to this blog will make using Gutenberg much less intimidating. Let’s hope Wordpress v7 doesn’t completely replace Gutenberg with Yet Another Editor for me to master.