Introduction

Welcome to the WordPress Block Editor Tutorial Series. This tutorial introduces screen reader users to the WordPress block editor by covering blocks in the context of WordPress, and offering some tips and tricks for getting things done as efficiently as possible in the new and more complex editing environment. Future tutorials are also in the works that will cover each of WordPress’s default blocks.

We’re not writing this because we think it’s time to jump on the block train. We decided to publish these tutorials because other users of assistive technology might find themselves in situations where their employers or clients have switched to the block editor and so those users find themselves in a situation where switching back and forth from block to classic editors creates more problems than it solves. (Spoiler alert: Switching back and forth really isn’t sustainable). Assistive technology users who want to experience the new editor will also find these helpful.

What Are Blocks In WordPress?

Blocks are the components for adding content in the new WordPress editor. They are used to transform a single document into a collection of discrete elements, each of which has an explicit structure. Block structure and settings are separate from the settings for the entire document, and block settings and document settings have their own distinct parts within the editor’s user interface.

Comments on Discoverability of Keyboard Shortcuts

We’ve tested and documented a significant number of shortcut keys in order to help make the editing experience as efficient as possible, but they were not easy to find. Most are not documented within the editor, and there is no link to any outside documentation to find further information. We made an educated guess that “richedit”, (the technical term for what WordPress is calling a “media rich editor”) implied that the new WordPress editor is supposed to be something like Microsoft’s WordPad. We looked up the keystrokes for that editor, tested them with the new WordPress editor, and our educated guess turned out to be correct. We could make that educated guess because we have the background and experience with screen readers and windows to make that possible. Most screen reader users, or even just average users, do not have that background. It would not occur to most to make that educated guess, and it shouldn’t have to.

We went with Wordpad and not Microsoft Word because while Wordpad is a richedit application in the technical sense, Microsoft Word is not. Furthermore, the block editor as “Microsoft Word for WordPress” is an unattainable goal as long as the block editor lives in the browser. The goal of “Microsoft Word for WordPress” is unattainable because Microsoft Word and the browser have entirely separate, and very different, document object models which never meet. Not all the Wordpad keystrokes work, so we have documented the ones that do.

Tools used for this tutorial

  • WordPress 5.5.3 using the twentytwenty theme
  • Browsers: Mozilla Firefox and Google Chrome; both browsers always kept up to date.
  • Screen readers: JAWS 2021 and 2020, NVDA 2020 and Microsoft Narrator

Frequently used keyboard shortcuts

Notes:

  • If a shortcut requires two or more keys at the same time, the keys are separated by a plus sign (+).
  • The shortcuts in this article refer to the U.S. keyboard layout. Keys for other layouts might not correspond exactly to the keys on a U.S. keyboard.

Editing Shortcuts

ActionShortcutContext
CutCtrl + XText and Blocks
CopyCtrl + CText and Blocks
PasteCtrl + VText and Blocks
UndoCtrl + ZText and Blocks
BoldCtrl + BText only
UnderlineCtrl + UText only
ItalicsCtrl + IText only
Insert hyperlinkCtrl + KText only
CancelEscapeText and Blocks

Move around in a document/block editor using the keyboard

ActionShortcutContext
1 character leftleft arrowText and Blocks
1 character rightright arrowText and Blocks
1 word leftCtrl + left arrowText and Blocks
1 word rightCtrl + right arrowText and Blocks
1 line upUp arrowText and Blocks
1 line downDown arrowText and Blocks
Beginning of lineHomeText and Blocks
End of lineEndText and Blocks

Edit and move text and graphics

ActionShortcutContext
Select previous characterShift + left arrowText only
Select next characterShift + right arrowText only
Select previous wordCtrl + Shift + left arrowText only
Select next wordCtrl + Shift right arrowText only
Select to beginning of lineShift + homeText only
Select to end of lineShift + endText only
Select previous lineShift + up arrowText only
Select next lineShift + down arrowText only

Delete text and graphics

ActionShortcutContext
Delete previous characterBackspaceText only
Delete previous wordCtrl + backspaceText only
Delete next characterDeleteText only
Delete next wordCtrl + DeleteText only

Specific to block editor

ActionShortcutContext
Switch between Visual and HTML EditorsAlt + Ctrl + Shift +MText and Blocks
Select Block typeSlash (/)Blocks only
Show/hide block toolbarAlt + F10Blocks only
Show/hide the settings toolbarCtrl + Shift + comma (,)Blocks only
Select all text in a blockCtrl + AText only
Select all blocksCtrl + A twiceBlocks only
Blocks navigation menuAlt + Shift + OBlocks only
Toggle full screen Alt + Ctrl + Shift + FBlocks only
Duplicate blocksCtrl + Shift + DBlocks only
Remove selected blocksBackspace or deleteText and Blocks
Insert block beforeAlt + Ctrl + TBlocks only
Insert block after Alt + Ctrl + YBlocks only
Move block up 1 level Alt + Ctrl + Shift + TBlocks only
Move block down 1 levelAlt + Ctrl + Shift + YBlocks only
Remove/delete block Alt + Shift + ZBlocks only
Navigate to the previous part of the editorAlt + Shift + P or Ctrl + Shift + `Blocks only
Navigate to the next part of the editorAlt + Shift + N or Ctrl + ` Blocks only

Inserting, Deleting and Changing Layout of Blocks

Inserting a new block

When starting a new page or post, a dialog appears welcoming you to the block editor. Move to the “close this dialog button” and press either spacebar or enter to dismiss.

From the block’s toolbar add a new block by either pressing the spacebar or enter key on the appropriate button. A place holder for a new block is inserted into the content area which prompts the user to start typing or press the slash (/) key to choose a block type. If using a screen reader, you will need to invoke forms or edit mode before you start typing or use the slash key.

If you are editing an existing page or post that already has blocks in the content area, you can add a block either before or after a selected block in the hierarchy. To add a block before the selected block press Control + Alt + T and to add a block after the selected block press Control + Alt + Y. Screen reader users will need to be in forms or edit mode.

You can also duplicate a block by pressing Control + Shift + D. This is useful if you have a block already formatted and want to duplicate this block along with its information in another location in your pages or posts.

Copying a block uses the standard Windows shortcut Control + C, which is useful for when your block is setup and formatted and you wish to share between other pages or posts. You can also move a block by using Control + X.

Choosing a block

With focus on the block place holder, press the slash (/) key to choose a block. A list appears with 60+ items from which to choose the block you need. The number of items in this list may change, however, at time of writing approximately 60+ items were available. Please note that screen reader users will need to be in forms or edit mode.

Use your up and down arrow keys to navigate this list until you get to the item you desire and then press the enter key. Do not attempt to use first letter navigation in this list as it does not work, only the arrow keys.

Changing your block layout

As you continue to compose your page or post, the blocks are enumerated 1 of 10, 2 of 10, and so on.

To move your block up or down in the hierarchy, first make sure you are focused on the block, make sure you are in forms or edit mode and then press Alt + F10 to bring up the block editing toolbar.

Use your right and left arrow keys to navigate this toolbar. As you press the right arrow keys, the first two (2) options on this toolbar are the buttons to move either up or down one (1) block at a time. Choose the appropriate button and press the spacebar or enter key to maneuver the block into the position of the hierarchy you desire.

You can also press Alt + Control + Shift + T to move your block up one position in the hierarchy, or press Alt + Control + Shift + Y to move your block down one position in the hierarchy.

Deleting a block

To delete a block, make sure that your focus is on the block you wish to delete, and in forms or edit mode press Alt + Shift + Z. Your block will be deleted.

Alternatively, press Alt + F10 to bring up the toolbar, then use the right arrow to move to the “More options button” and press either the spacebar or enter key to drop down a list of items, then down arrow to the option for “remove/delete block” and press the enter key on this item and the block will be deleted.

You can press Control + A twice to select all the blocks in the content area and press either the backspace or the delete key to get rid of all the blocks in the content area. You want to use caution when using this method, as it may not give you the result that you are looking for.

Document View versus Block View

For the sake of this tutorial, we will refer to editor or view, as each has a block element involved and we will attempt to untangle the confusing terminology.

Do not confuse the editing views with the editors themselves. You can switch between the two (2) editors by pressing Alt + Control + Shift + M. The block editor is also called the “visual editor” and the text/HTML editor. These editors along with the blocks are the primary focus of this tutorial. When using the text editor, be aware that block comments will show up as part of your content, so you’ll need to be mindful of those when making edits. We do not recommend attempting to memorize all the block comments, and if you find yourself in a situation where you need to use anything other than the block editor, coordinate with your other content editors on who’s editing which pages or posts because switching back and forth, even between the traditional classic editor and the block editor, gets very messy very fast.

Document view

After inserting your block of choice to work with, you will have the add block toolbar still available. Just after this toolbar are two (2) buttons used to switch between views.

The document view is used for configuring certain elements about your page or post prior to publication, such as the following:

  • Status and visibility
  • Permalink
  • Categories
  • Tags
  • Featured image
  • Excerpt
  • Discussion
  • Post attributes

It is recommended that you consider the above items before you publish to make sure everything is in place to work as you intended on your web site.

Explore these attributes on your own as it is beyond the scope of this tutorial currently to write up these options. However, this does not mean that a future revision of this tutorial may not have these attributes documented.

Block view

The block view is different for each block that you insert into your content area, so to keep this simple we will use the paragraph block to explain the configuration options available. Each block will be documented separately along with its configuration options in block view in more detail when the document for each block is introduced and published.

For the paragraph options you will have the following at the time of this writing:

  • Topography – for setting the font size
  • Color Settings – for setting text color
  • Text Settings – choose either drop cap or large initial letter
  • Advanced Settings – insert a hyperlink or modify the CSS for your choice of style

For other formatting options for the paragraph block, look at the tutorial specific to working with the paragraph block which will have much more detail.

Inserting and Deleting Hyperlinks

This tutorial is going to assume that you have a list block created with three (3) list items.

For example, my list looks like the following:

  • Visit John
  • Call John
  • Email John

Since this list is now established, let us turn the text of the list into useable hyperlinks.

First select the list block, and if you are using a screen reader turn on your forms or edit mode. Use your navigation keys to move to the first part of the text and using text selection keystrokes, select “Visit John.” Tip: be sure to only select the text, because if you accidentally select the blank at the end of the first item, the first two (2) items in the list are both incorporated into a single link.

Once your text is selected, then press the keystroke of Control + K and the insert link dialog appears prompting for a URL. Type the following in this field: https://www.customerservant.com and then you should hear that one (1) option has been found. Tab to the submit button and then press your spacebar or enter key. You should hear a message stating that a link has been inserted.

This is how to insert a hyperlink using the http or https protocol, but what if you wish to use another protocol to insert a hyperlink?

Let us select the second list item text remembering to only select the text and not the blank character at the end of the line. When you have this selection made, then press the keystroke of Control + K and in the edit field type tel://8005551212 and you should hear that one (1) item has been found. Tab to the submit button and press either your spacebar or the enter key. You should hear a message that the link has been inserted.

For the last list item, again select the text to become a link being careful not to get the blank character at the end of the line. Press the keystroke of Control + K and then type mailto:john@jcarson.wtf into the edit field and you should hear a message stating one (1) item has been found. Tab to the submit button and either press your spacebar or the enter key and you should hear a message stating that the link has been inserted.

It is now time to test your links to make sure they do what you intended to do.

Note: We used three (3) examples to show how to insert hyperlinks using different protocols just so you do not have to experiment to figure out these procedures.

Deleting or Removing a hyperlink

Deleting or removing a hyperlink is just as easy as inserting one, just select the text that is already a hyperlink using the cautions already mentioned in this tutorial and press the keystroke of Control + Shift + K and you should hear a message indicating that the hyperlink has now been removed.

What blocks can you insert and delete hyperlinks?

This list will eventually evolve with continuing revisions, however, so far, we have found that inserting and deleting hyperlinks works with the following blocks:

  • Paragraph
  • Heading
  • Image
  • Lists

This tutorial has covered a lot of ground, and we’ve attempted to lay some comprehensive groundwork in order to get users started. More tutorials are coming, but if you have any questions on this one or feel we’ve left something critical out, feel free to get in touch on social media or through the contact form on this website. Until then, happy editing, (or at least, we hope your editing experience becomes less complex).

Introduction

This is the first in a series of tutorials on using WordPress’s block editor with a keyboard. We’re assuming that you’re using a screen reader as well, but we’ve also tried to include keyboard navigation tips for times when a screen reader is not present.

Inserrting a new block

When starting a new page or post, a dialog appears welcoming you to the block editor. Move to the “close this dialog button” and press either spacebar or enter to dismiss this welcome dialog.

From the blocks toolbar choose to add a new block, by either pressing the spacebar or enter key on the appropriate button. A place holder for a new block is inserted into the content area which prompts the user to start typing or press the slash (/) key to choose a block type.

Choosing the heading block

With focus on the block place holder, press the slash (/) key to choose a block. A list appears with 81 items in which to choose the option you need. The number of items in this list may change, however, at the time this was being documented only 81 items were available in WordPress 5.5.1.

Use your up and down arrow keys to navigate this list until you get to the heading item and then press the enter key. Do not attempt to use first letter navigation in this list as it does not work, only the arrow keys.

Changing your block layout

As you continue to compose your page or post, the blocks are enumerated 1 of 10, 2 of 10, and so on.

To move your block up or down in the hierarchy, first make sure you’re focused on the block and then press Alt + F10 to bring up the block editing menu.

Use your right and left arrow keys to navigate this menu. As you press the right arrow keys, the first two (2) options on this menu bar is the buttons to move either up or down one (1) block at a time. Choose the appropriate button, and press the spacebar or enter key to maneuver the block into the position of the hierarchy you desire.

Choosing your heading level

By default when a heading block is inserted into the content area it is automatically designated . as a heading level two (2) element.

To change the heading level, first make sure to be focused on the block and press Alt + F10 to bring up the menu bar, and right arrow to the button for heading level.

Press your spacebar on this button. A list of buttons appears for each heading level, to navigate this list, however, you will need to use the left and right arrow keys to choose the heading level you desire.

Once you have the heading level, press either your spacebar or enter key to confirm your choice.

Inserting text into the heading block

To insert text into the heading block, just simply start typing if you have your focus on this block. Screen reader users will need to make sure that their screen reader of choice is in either forms mode or editing mode.

Editing text in the heading block

Editing text in the heading block can be a little tricky at first with a keyboard, however, it can be done with practice.

Make sure you have the heading block focused, then use your arrow keys to navigate to the text you wish to edit. Use your keyboard commands for selecting text and make your modification.

Updates: has responded to the Tavern article, as has Adrian.

WPTavern disagrees with Studio 24’s decision to drop WordPress over Gutenberg. I was going to write a long comment on that post, but then I figured I’d just address it on my site.

The Tavern’s disagreement hinges on the W3C prioritizing accessibility over its commitment to open source. And I’m wondering why that’s a bad thing.

Open source as a rule, (and FLOSS in particular, from Stallman on down), continues to consider accessibility one of those things that should be left up to the choice of the developer instead of something that should be implemented so that everyone can enjoy the freedoms granted by the GPL and other licenses. And anyone who has spent any time advocating for accessibility within the free spoftware space knows this. There’s a reason advocates are giving talks about the rights aspect of this instead of technical talks.

That talk’s from 2017, and I can’t think of another talk given by an accessibility advocate in that space since then. I can’t speak for anyone else but I get the impression we’ve finally just given up on trying to convince the Free Software movement that accessibility should be a requirement instead of a nice-to-have at best.

So it’s kind of nice to see the W3C flip tables over this.

Prioritizing accessibility over open source/free software isn’t the wrong thing to do, it’s the right thing to do, especially given the state of accessibility in the FLOSS space.

With regard to Gutenberg specifically, out of the eight projects I’m working on right now, two clients can use it without wanting to throw something, and only one of them really enjoys it. That client doesn’t have a disability and doesn’t use assistive technology. I still find Gutenberg to be an efficiency nightmare, and I’ve been using it for seven months now. And while I don’t think there’s a person alive who would say that the accessibility of the thing hasn’t improved, the part of that talk by Joe Dolsen left out is that the issues that have been closed and the accessibility successes are a start.

There’s also this, from his post on this subject:

When I read that statement, I feel like it implies that I gave a positive report on the accessibility state of Gutenberg in a way that isn’t really accurate.
Both those statements are absolutely true: two-thirds of the issues reported in the initial accessibility audit of Gutenberg have been solved, and the
overall accessibility is, indeed, vastly improved over the release, as would be expected given the first piece of information.
But it ignores the fact that those accessibility issues are not the only concerns raised on the project. They only encompass issues that existed in the
spring of 2019. Since then, many features have been added and changed, and those features both resolve issues and have created new ones. The accessibility
team is constantly playing catch up to try and provide enough support to improve Gutenberg. And even now, while it is more or less accessible, there are
critical features that are not yet implemented. There are entirely new interface patterns introduced on a regular basis that break prior accessibility
expectations.
And the statement that Gutenberg is vastly more accessible than at release is not particularly significant. At release, it was woefully inadequate; now
it’s bearable and largely usable, but in no way enjoyable. And in certain respects, it is lacking extremely basic features, such as support for adding
video captions within Gutenberg.

Note also Joe’s comments regarding WordPress and internationalization. They’re important, and I’m seconding them completely.

Improvement is excellent, but it’s not done. And speaking as someone who has to use Gutenberg on a pretty regular basis, it’s not ready to be deployed if you’re concerned about whether or not people with disabilities can add content to your system.

I hope that the W3C’s decision will convince WordPress’s leadership to prioritize accessibility at a higher level. But hope is not a strategy, and I don’t think organizations or individuals should be expected to stick with something that clearly isn’t meeting their needs or is even causing problems for the sake of their devotion to FLOSS.

I think Gutenberg is a great idea, despite the all-too-frequent flare-ups that still happen over accessibility issues. But I definitely don’t enjoy using it, and I don’t know any people with disabilities who enjoy using it either. And WCAG 2.0 is the minimum. You could completely conform to WCAG 2.0, and it doesn’t mean you’ve created something people with disabilities can use as effortlessly as everyone else.

Until Gutenberg gets to a point where it’s as easy to use as the classic editor, (if it ever does), organizations who either employ or want to employ people with disabilities are going to continue to drop WordPress over it. And telling them to fork WordPress or to maintain the classic editor plugin after WordPress stops doing that isn’t a solution to the problem. It’s about the most obtuse thing that could be said.

Yesterday I posted that I was contemplating migrating this site over to the Gutenberg world. There are a couple of reasons for this, and the most pressing one is that John, (whose greatest hits include experimenting with Gutenberg and Twentytwenty back in November and consequently providing the catalyst for some fixes that went into WordPress 5.3), and I are have decided to professionally pool resources. He’s been working on some smaller projects for me, and he likes kicking the tires on Gutenberg and doesn’t want to give it up for the classic editor.

OK, so we’re doing this. But for this site, it’s going to take some planning. First, there are several custom post types this site relies on, and it also heavily relies on the suite of plugins which enable WordPress sites to participate in the Indieweb movement. I’m definitely not giving that up, so this means that there are going to have to be some contributions to those plugins to make them suitable for Gutenberg use.

I’ve volunteered to be the lab rat for this, since I depend on it and I don’t want to give it up and go back to not-indieweb. I’ve decided to journal the entire process, starting from Day 0 until we get everything finished.

after doing some initial planning, (determining what custom post types are in play, plus post kinds), a separate development environment has been set up, which has Gutenberg installed. John’s using Twentytwenty on a smaller site he’s working on, so I think the development environment will have a Genesis theme for its base install. I’m also chatting back and forth in Indieweb Slack.

I figure if I’m doing this, may as well jump off the deep end. We have a target date of just after Labor Day for launch, and I’m going to do my best to stick to that. And I’m documenting the entire process, challenges and all. It should be interesting.

I bookmarked a post by Heydon Pickering entitled Web Accessibility Is Out To Get You And Make You Feel Sad and my sharing of that post received some feedback from one of the developers who was apparently involved and who has made the accusation that Heydon is attempting to hide his abuse by lying about everything he did during the conversation.

I’ve asked for a link to the relevant conversation, and so far haven’t received a response, so in the meantime, (assuming that this individual has the best of intentions, giving benefit of the doubt and all that), I’d like to get an honest answer to the question which forms the title of this post, because as both an accessibility practitioner and as a person with a visible disability who quite literally is reliant on whether or not accessibility is viewed as more than just a nice-to-have by developers, I’m tired.

I bookmarked Heydon’s post because quite frankly it telescopes excuses for inaccessibility I hear on a regular basis from developers, and yes, I’m glad someone can manage to create some humor borne out of what is very draining: Advocating for accessibility.

Advocating for accessibility and in some cases fixing accessibility issues in code is draining because there appears to be no end in sight, and experience tells me that even if I wade into a code base, make accessibility fixes, leave detailed comments explaining the fix, more often than not for free, and the pull request is accepted, that fix will be reverted or broken in some other way and it’s only a matter of time as to when this will happen. And that’s the ideal situation. I can wade into a code base, propose a fix, and for the most part be guaranteed a protracted argument, sometimes over a single line of code, about why that accessibility fix won’t go in, and we swear we care about accessibility and we’re never going to admit anything but the purest of intentions and don’t you dare call us ableist because that will hurt our feelings.

And I’m far from the only accessibility practitioner who gets to experience things going down like this.

If you’re a person with disabilities, even one who doesn’t professionally work in the accessibility space, you are expected to advocate and educate for your entire life, most of the time for free, except when you’re inspiring the living daylights out of abled people through the videos and photos they take, often without your consent, which they then post on social media and through which they enjoy viral internet fame.

Oh and you’re also expected to be polite, ask nicely for the accessibility crumbs you manage to catch falling from the table, and God help you if you file a lawsuit because lawsuits are bad and well to be honest they’re evidence of your ingratitude.

This is a battle we have been waging on the web for the last twenty years. Accentuating the positive hasn’t worked. Providing business case after business case hasn’t worked. Pointing out the benefits to everyone who isn’t a person with disabilities hasn’t worked. Fixing your code for free hasn’t worked. Thousands and thousands of hours of free advice and training and examples hasn’t worked.

So yeah fellow developers, I’d really like to know at what point accessibility folk are permitted to lose our patience with all this without you stomping your feet and crying fowl, and I’d really like to know what exactly will convince you to do the needful, learn the basics, and start creating things that everyone can use without having to badger you into it so we can quit going over the basics time and time and time again and focus on fixing actual issues.

What exactly is the magic solution to ending this fight and not spending the rest of my life advocating for my civil rights and training you and inspiring you because if there is some magic solution I will gladly employ it so I can stop giving a damn about accessibility and just live my life like a normal person.

Signed:

A web developer who is absolutely exhausted by constantly fighting with the rest of you.

This post is the result of a quick discussion on Twitter that I think should be saved for later bookmarking/reference. Also, my Twitter client has some weird focusing issues which means the first part of the reply was sent to the wrong person. (Sorry about that Adrian). Lastly, Twitter seriously broke the thread so if you try to search for related posts you’re missing half of it.

Wendy Delfosse asks on Twitter:

Best places to start for learning to use WordPress with visual impairment? A user wants to know how to pick a great theme since he won’t be able to verify the design himself. Any tips greatly appreciated.

(Source).

More specifically, the user Wendy is asking on behalf of is looking for help with making sure their site looks good with background images, fonts, ETC. I responded in multiple replies with several tips based on my experience. Here are those tips.

Picking a great theme is very much dependent on what you consider great, including visually. Also, in the case of visually impaired, blind specifically, whether you have visual elements like images, for example, to help make a theme look like the demmo, except with your content/site.

So, to start with, does this user have a concept of what they’re looking for visually in a site? If not, I’d say start with an accessibility ready theme and then, once you’ve figured out branding/colors/images ETC., go from there.

Also keep in mind that no out-of-box theme will have everything you want. So make a list of things that are essential in a theme, then nice-to-haves, and then, once ready to grow, decide on budget for hiring out the visual work of site building/design.

Find a sighted person you can trust. Looks good is also unfortunately one of those things that to a large extent is in the eye of the beholder. Knowing what you want from a site in terms of who the audience is for the site is also helpful in this, because it helps narrow down the “looks good” part.

If it’s something like a personal site though, I’d go with picking an accessibility ready theme, and then, after that, don’t worry so much about how it looks to others except for basic contrast issues, which accessibility ready themes will cover adequately. In short, if it’s a personal site, just be yourself.

One last thing. When picking a sighted person to trust with this stuff, stick with one person. Be careful about second opinions as sighted people who are not designers/familiar with design principles/accessibility will give you widely varrying and often conflicting results. It’s kind of the same thing as asking a random sighted person how your clothing looks.

Off the top of my head, I think this covers the basics from this perspective. But, if there’s something I haven’t thought of, feel free to leave it in the comments, and I’ll update this post accordingly.