Unblocking the WordPress Block Editor | AppleVis

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.

This blog uses the following terms.

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.

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.

Here are the regions.

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.

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:

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

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:

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.

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.

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:

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.

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

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.

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.

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.

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:

In the Editor Content region, using the visual editor:

And in the code editor:

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.

This content was originally published here.