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.
- Select all and copy your page or post content (Command+A, Command+C).
- Open Wordpress and create a new page or post. When the visual editor opens, VoiceOver focus is in the title heading block.
- 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.
- 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:
- Select the desired anchor text.
- Press Command+K.
- Type http://applevis.com. As you do so, ignore VoiceOver announcing suggested URLs.
- 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.
- In your admin backend, create a new page or post.
- When Gutenberg opens, it’s already in the visual editor, with focus in the title block.
- Type the title text and press Enter.
- This opens a second block, and it’s a paragraph block by default. Enter the introductory paragraph text, then press Enter.
- 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.
- This opens a fourth block, again it’s a paragraph block by default. Go ahead and enter the final paragraph text.
- Press Escape to leave edit mode and enter navigation mode. Use Tab and Shift+Tab to move between the blocks and review their content.
- 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.
- 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.
- In navigation mode, when using Tab and Shift+Tab to move between blocks, I wish VoiceOver’s focus didn’t lag.
- 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.
- 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.
Comments
Useful tutorial
I find this tutorial very useful. I took me a while to figure out the hotkeys since I'm a Windows user but from my experimentation the hotkeys you described work just fine; I only needed to substitute command key with the control key and the option key with the alt key.
It came in handy
Two weeks since I posted this, and two weeks without touching the visual editor. Then, suddenly, I had to modify a web page, and of course I had forgotten most of what went into this article. A quick read-through refreshed my memory. Whew.
Control+Accent not available in foreign keyboards
Hi, I would like to give my contribute on this; first of all with a question:
Accent, that sign you use combined with control, to switch from a region to another: in the American/English layout it's at the left of number 1 key, but Italian keyboard for example doesn't have it, and, there is no way to go to the editor's regions - or is it the same of alt+f10? Don't know what it is on mac, maybe command+f10, or option+f10?
Then, let's come to the contribute:
You mentioned writing a page or article using a local editor? Well, good idea, but it might be even better if you know Markdown syntax.
On my mobile devices I have the Drafts app, with a Pro subscription - yes, it's even on Mac if you're interested; it's a very powerful text and also scripting editor if you want, and it has a Markdown keyboard embedded but MarkDown works with any text editor.
The syntax should be documented also on AppleVis post editor, as you could have noticed, but let me give you a short anticipation:
Let's assume you're writing a page about Gutenberg editor.
So, you start with first paragraph, introduction:
"I want to introduce how to use gutenberg editor. If you want to continue, read on".
Then you want to place a separator, to create a distance from the intro to other chapters? Well, you simply enter two empty lines to change paragraph, then you insert three dashes. Like this. ---
Then, another two empty lines. That is, press Enter key twice. This creates a new Paragraph block, otherwise WordPress's markdown rendering understands you've just pressed Return, but not to change paragraph.
Then, let's assume you want to place a title? Simple as the hash sign, #, followed by a space, then followed by the sentence you want as a title. A single # is a heading level 1, ## is level 2, till ###### that's level six.
Or you can have a single dash, followed by a space, which starts an unordered list.
Or the GreaterThan sign, >, for quotes.
Or [anchor text](URL) for links.
After finished editing the local file, you do it simply as copy/paste from the editor to WordPress.
Yes, even if you have written it on the phone and then you want to export it blogging from the computer; depending of course on which editor you use, if you saved it into a cloud platform allowing you to pass through many systems.
I'm a crazy geek and I pass the files from Drafts on iPad to DropBox or PCloud -other life time cloud service I have -, then go on from WordPress to editor with no effort.
And you know what? The best part is that same syntax can be easily used from Gutenberg itself, so, if you press ## then space in a new block, it'll automagically turn into a heading level 2 letting you write the words you want to insert in the title!
And, for what concerns the final so-called "wishlist" you mentioned?
Here they might get lost, but you can directly pull a request to the Gutenberg's github issues area.
https://github.com/WordPress/gutenberg/issues
hth
Good feedback
Thanks Elena. I hadn't discovered Gutenberg's markdown support. I'll look into opening issues on Github. So many issues, so little time.
As an alternate method to move between regions, press VO+U, arrow to the Landmarks menu, then select the region of your choice. I've edited the blog to include this method.
Keystrokes for regions
Well, I have also asked around, and: to navigate through regions, you can of course use screen reader's standard region-to-region navigation shortcuts such as "r" for Jaws, NVDA I don't remember, VoiceOver as you mentioned using the rotor.
There also should be an alternate command combination such as shift+alt+n for next, shift+alt+p for previous - alt = option on Mac, but at least on Jaws this does not work properly.
I might suggest to developers if they add a method to customize keys...
Free block editor class
AppleVis member AbleTec (Jackie McBride) and I will co-lead a free block editor tutorial via phone conference, Friday, April 26, 2024. The session will cover both Windows and MacOS. Here's a link for more block editor tutorial information.
Markdown
Multiple people have told me that you can paste markdown into the block editor. I've finally discovered why this wasn't working for me. If it doesn't work for you, try using Command+Shift+V to paste and match style.
Reminder: Free block editor class
The free block editor tutorial will be held tomorrow. Here's a link for time and dial-in information.
php code`
Man, I wish the code editor supported either php code or Java. There's loads of stuff I'd like to be able to do with one of my sites with php but yeah. Would love for this to become a thing directly. I'd rather not have more plugins than I need.
A Question About Visuals
Hi,
Thanks so much for this tutorial!
If I were to create post or page content in Word for example, and then paste it into the Block Editor, how does this affect the overall look of the page? For example, if someone sighted had created one post using the block editor itself and I have created one in Word and pasted it in, will the two have a different font, text style etc? The same question applies with creating posts locally using Markdown and pasting that in. I would prefer to use the “quick solution” and minimise interactions with the Block Editor as much as possible, but obviously I want the site to look professional and consistent throughout, rather than looking like a Word document on a webpage.
I’ve never had any vision so that may not be a great description of the visual terms, but hopefully my question makes sense.
Pasting from Word should not change visual appearance
I think you're worried that if you copy 24 point Arial from your Word doc, and your co-admin has been pasting 12 point Times, will you end up with two very different font types and sizes. The simple answer is no. The paragraph style itself will carry over, by setting the type of each block, such as paragraph, heading, bullet list item, quotation, etc. But the appearance of the different block types is determined in the Editor Settings, and ultimately in a style sheet that is identical across your entire Wordpress site.
The next logical question: How, then would you create one block of text with its own unique font type and size? Good question. That's something I've never needed to do. A web search might turn up some guidance. Another great resource is the wp4newbs email list.
Editing the Site Globally
Hi Paul,
Thanks for your answer above a couple of weeks ago.
Are you familiar with editing the global aspects of the site, such as the header at the top, main navigation menu etc? I’ve become quite comfortable with editing posts in Gutenberg, but I just cannot for the life of me get to grips with creating and reordering menus like I used to be able to with the classic editor. Any tips or tutorials on this?
Re: Editing the Site Globally
Good question. This blog post concerns only the editor for pages and posts. But the editor for widgets and menus has also changed, and so has the editor for customizing theme appearance. Sorry, I haven't played with any of that stuff since losing my eyesight, and I just don't have the bandwidth to do a deep dive on those topics at the moment.
Full site editing
My own experience: Fill Site Editing works as Gutenberg, so the accessibility is mostly the same.
Of course when you have to deal with navigation menus, buttons, and so on, you must know what you do and overall get confident with the block toolbar and block settings, together with the content. With the GROUP block as well, because when you are modifying for example a sidebar, you need to have grouped elements.
Sighted help is needed when you have to resize pages and change the colors.
I hope that learn.wordpress.org will get a Full Site Editing course soon
Yep they did change that…
Yep they did change that aspect ever cense I last used it and even now I'm finding stuff new. It's entirely possible to do full site editing with blocks, however, I'm using windows for this and don't have much experience with the mac, but that's gunna be the same mostly with a few shortcut mods. You can kind of do color and page sizing, but I'd get sighted help just to see how it's all gunna look visually and then you can change stuff as needed. I'm bad with colors so have not a clue on what colors look good with what and background colors to use and what not. I'd like to add more preset colors to my theme I'm working on for WP because they ain't that many to choose from but I don't know my hex values as much as I should and it's been a while as I haven't used hex either.
Even with this post, WP is overwhelming
Anybody got any suggestions for a template for a bog-standard 'micro blog' style WP site? I only left MB because of issues logging in all the time.
ClassicPress
Hi all,
I asked a similar question about full site editing on Mastodon and someone has pointed me to ClassicPress that I thought might be worth mentioning on here. Basically, it's a fork of WordPress 4.9 (the last version before the block editor was added) and is regularly updated with new features and security enhancements. It sounds like they've removed a lot of the bloat that comes with WordPress as well to make sites run faster and more responsive, so it is different to running standard WP with the Classic Editor installed.
I haven't had chance to investigate this yet other than looking through their website and reading some comments about it, but it sounds interesting as long as it's not too stuck in the past.