Gutenberg: Keyboard shortcuts support

[jasmussen]

For accessibility and power-users both, we should always think about keyboard support. This was first brought up in #61, but deserves being fleshed out more.

The editor already has keyboard support for most formatting controls, including the "Paragraph" type switcher, which we are pondering moving to the side. Though since this will likely expand a fair bit beyond _paragraphs, headings and preformatted_, maybe that needs love too.

Many of these are existing keyboard shortcuts that should probably stay intact for back compat.

Inline formatting:

• [x] Bold ⌘B
• [x] Italic ⌘I
• [x] Link/edit link ⌘K (or paste around selected text) Being handled in #4411.
• [x] Unlink ^⌥S Being handled in #4411.
• [x] Strikethrough ^⌥D Being handled in #4411.
• [x] Change heading size ^⌥↑ for increase, ^⌥↓ for decrease See https://github.com/WordPress/gutenberg/issues/71#issuecomment-357252369.

Hidden (?) controls:

• [x] Undo ⌘Z
• [x] Redo ⌘Y
• [x] Cut ⌘X
• [x] Copy ⌘C
• [x] Paste ⌘V
• [x] Select All ⌘A See #4369 now.
• [x] Keyboard shortcuts cheat sheet — currently ^⌥H, should it instead/also be Shift ?
• [x] Underline ⌘U
• [x] Code ^⌥X Being handled in #4411.
• [ ] Align center ^⌥C
• [ ] Align left ^⌥L
• [ ] Align right ^⌥R
• [ ] Justify ^⌥J
• [ ] Bullets ^⌥U
• [ ] Ordered list ^⌥O
• [x] Remove link ^⌥S Being handled in #4411.
• [ ] ⌘+ENTER (Ctrl+Enter for Windows) to create a separator

Markdown-esque shortcuts/syntactic sugar:

• [x] Code: wrap text in backticks, `
• [x] Bullets: * or - on newline
• [x] Ordered list: 1. or 1) on newline
• [x] Blockquote: > on newline
• [x] H2-H6: ## - ###### on newline
• [ ] Horizontal line: --- on newline

Insertion/block level controls:

• [ ] Insert block: ^⌥M (for fallback) and / on newline (see #24)
• [ ] Move block up ^⌥↑
• [ ] Move block down ^⌥↓
• [ ] Open block type switcher ⌘~ then ↑/↓ and Enter for select
• [ ] Toggle between block types ~

Inserter:

• [ ] Invoked where the cursor is, by typing / on newline or pressing ^⌥M, then ↑/↓ and Enter for select

[jasmussen]

These two:

• [ ] Open block type switcher ⌘~ then ↑/↓ and Enter for select
• [ ] Toggle between block types ~

probably need the most discussion, as getting these right can potentially make for a _killer_ feeling while writing.

Imagine this: _type type type_, churn out a blogpost, / on a newline, arrow down to image, enter, pick image with arrowkeys, enter to insert, write another line, press ~ twice to instantly switch it through heading and then to blockquote. Done.

In this situation, simply pressing ~ while inside a block switches it to _the next compatible blocktype_, so a paragraph would cycle over heading then to quote, whereas a gallery might cycle between gallery types. ⌘~ would actually open the switcher list so you could see the compatible blocktypes and pick one using arrowkeys.

Quip has this shortcut, worth trying out. But they use backtick `, which we are using in a markdown-esque way for code.

Important also to think of international keyboards. On US keyboards, the ~ character is in the top left, which makes it a _sweet deal_, easily accessible, whereas euro keyboards put the tilde under ⌥^, which is a fair bit more cumbersome. Any other ideas?

[jasmussen]

This one also deserves lots of thought:

• [ ] Change heading size ^⌥↑ for increase, ^⌥↓ for decrease

For context, these shortcuts assume that a "Heading" is a single block type, and the _heading size_ is a block-level property of that style. Mockup:

👆 Note, that mockup has a different style of block level controls than the UI prototype currently has.

So the flow would be:

• write text
• press ~ to switch to next compatible block type, i.e. Heading — this would convert the paragraph to a h1 (or h2?)
• press ^⌥↓ to convert the h1 to a h2

[afercia]

Worth reminding some of these keys are not available on all the keyboard layout, for example ~.

[ellatrix]

I can look into part of this together with the other text shortcuts, and where it touches Editable.

[paaljoachim]

I think it would be nice to include keyboard shortcuts for the most used blocks. As it would be a quicker way to add the blocks one use over and over again. Perhaps even have a mention of the shortcut beside the most used blocks similar to various program list shortcuts.

[jwold]

I've been thinking about the benefits of being able to write an article completely from the keyboard, without using a mouse. This has serious benefits for accessibility as well as for staying in the flow (kind of like when using Markdown and you can just keep writing while adding in quick formatting)

The ideal flow here could go like:

• Start typing a few paragraphs
• Type shortcut to open picker
• Start typing “qu…” and have the _quote block_ pop into view on the inserter and be highlighted as the number one result (https://github.com/WordPress/gutenberg/issues/1064)
• Press return/enter on the keyboard and have the block insert into the editor
• Write your quote
• Press tab
• Write your citation
• Press enter twice
• Continue typing

[jasmussen]

Love those thoughts, @jwold, so much so that it was planned for a long time to use /, like Slack and IRC, to invoke a searchable block selector dialog. See https://github.com/WordPress/gutenberg/issues/323#issuecomment-297750766 for full mockups.

This is a feature I'd like to resurface, but we've punted for now as it isn't critical to V1.

[jwold]

Awesome! Would love to have this revisited in the future. Agreed that it isn't needed for a V1 launch though.

[nicolinuxfr]

One keyboard shortcut request:

• [ ] ⌘/ctrl + s to save changes.

It works fine with the existing editor and I miss it on Gutenberg.

[JDGrimes]

• Link/edit link ⌘K (or paste around selected text)

Yes please, this is something that I miss from the old editor.

[ellatrix]

@jasmussen What is left here? :) I'll go through your list and erase items that have been done.

[ellatrix]

Also, what does ^ and ⌥ mean?

[nicolinuxfr]

Mac shortcuts for control and option/alt, respectively.

[ellatrix]

On my keyboard, option and alt are the some buttons. Also, from googling its seems ⌥ is option?

[jasmussen]

Yeah I think I meant ^ to mean Ctrl (the Mac version).

[jasmussen]

Also, I'll go through this list tomorrow! Thank you!

[ellatrix]

For some of these, it might be best to follow hat core does now (different for Mac and windows): https://github.com/WordPress/wordpress-develop/blob/186f963c34e64aba15294e1416a598533809ba21/src/wp-includes/js/tinymce/plugins/wordpress/plugin.js#L235

[jasmussen]

@iseulde

What is left here? :) I'll go through your list and erase items that have been done.

Wow, amazing progress. This is coming together!

Wanted to add notes on these:

Insertion/block level controls:
Insert block: ^⌥M (for fallback) and / on newline (see #24)
Move block up ^⌥
Move block down ^⌥
Open block type switcher ⌘~ then ↑/↓ and Enter for select
Toggle between block types ~

Inserter
Invoked where the cursor is, by typing / on newline or pressing ^⌥M, then ↑/↓ and Enter for select

These are _suggestions_, and they are so old now that they might very well not be relevant anymore. It's totally fine in implementation to decide that a different shortcut makes more sense.

For example, I think ⌘+Shift+↑/↓ might be better for moving blocks:

[afercia]

Just to note that some of the keys suggested here are not available on some non-English keyboard layouts. For example, there's no tilde character in many keyboard layouts:

Open block type switcher ⌘~ then ↑/↓ and Enter for select
Toggle between block types ~

These won't work universally. Considering also #3218 I'd tend to think the only way to make shortcuts available to all users, is to make them configurable.

[jasmussen]

Agree with Andrea, that particular shortcut might need to be rethought, and keeping past shortcuts in mind (in the case of the block switcher, the inspiration is the paragraph dropdown).

[ellatrix]

@jasmussen I assume "Move block up ^⌥" needs to be "Move block up ^⌥↑" If so, that would be conflicting with heading increase? Same other way.

[jasmussen]

@jasmussen I assume "Move block up ^⌥" needs to be "Move block up ^⌥↑" If so, that would be conflicting with heading increase? Same other way.

Yes that was the intent, the ↑ and ↓ must've been eaten in a bad copy paste, sorry about that.

If it is a common standard that those shortcuts in WordPress have always set heading sizes, I can see a good reason to keep them as such. But I do love that shortcut, and I think people will want to move blocks around rather often, so we'll want to find an equally nice shortcut for that then. What modifier keys haven't been spent for the ↑ and ↓ keys?

[ellatrix]

Oh, we don't have those up and down shortcuts in core, only the numbers. :) So then we just don't add those.

[ellatrix]

I corrected the text.

[ms-studio]

I'm wondering if there's a way to make the shortcuts discoverable in Gutenberg? In the classic editor, some of the shortcuts are revealed when hovering over a tool, and the whole list can be displayed.

Is there something similar under consideration for Gutenberg?

[jasmussen]

@ms-studio

I'm wondering if there's a way to make the shortcuts discoverable in Gutenberg? I

Yes, we are looking at that in #2980.

[bph]

I have not seen in on the list, yet:
Highlight text and mark it as a Heading.
The current editor allows for these keyboard combos:

use case work flow (on a Mac)

• Type your subheaders
• user command + shift + arrow left to highlight
  
  
  
  • use option + control + 2
  
  

http://recordit.co/QduuWAufki

[markjaquith]

Related: #5805

[afercia]

@jasmussen looking at this during today's a11y bug-scrub: do you want to keep it open as a tracker for all the other related, specific, issues or close it?

[jasmussen]

Definitely close, as I believe we have most in, thanks. If things are missing let's open specific issues for sure. Thanks for the ping! 🍷

[afercia]

Ok thanks!

[abrightclearweb]

Here is a list of the Classic Editor keyboard shortcuts for Mac with a note of which ones work in Gutenberg

Default shortcuts, Cmd + letter:

Letter | Action | Works? | Letter | Action | Works?
-- | -- | -- | -- | -- | --
u | Underline | yes | b | Bold | yes
i | Italic | yes | x | Cut | yes
c | Copy | yes | v | Paste | yes
a | Select all | yes* | z | Undo | yes
y | Redo | yes |   |   |  

* Press once to select a block. Press twice to select all blocks.

Additional shortcuts, Ctrl + Alt + letter:

Letter | Action | Works? | Letter | Action | Works?
-- | -- | -- | -- | -- | --
1 | Heading 1 | no | 2 | Heading 2 | no
3 | Heading 3 | no | 4 | Heading 4 | no
5 | Heading 5 | no | 6 | Heading 6 | no
7 | Paragraph | no | q | Blockquote | no
d | Strikethrough | yes | x | Code | yes
c | Align center | no | r | Align right | no
l | Align left | no | j | Justify | no
u | Bulleted list | no | o | Numbered list | no
m | Insert/edit image | no | s | Remove link | yes
z | Toolbar Toggle | no | t | Insert Read More tag | no
p | Insert Page Break tag | no | w | Distraction-free writing mode | no
h | Keyboard Shortcuts | no |   |   |  

When starting a new paragraph with one of these formatting shortcuts followed by a space, the formatting will be applied automatically. Press Backspace or Escape to undo.

  |   | Works? |   |   | Works?
-- | -- | -- | -- | -- | --
* | Bulleted list | yes | 1. | Numbered list | yes
-| Bulleted list | yes | 1) | Numbered list | yes

The following formatting shortcuts are replaced when pressing Enter. Press Escape or the Undo button to undo.

  |   | Works?
-- | -- | --
> | Blockquote | yes *
## | Heading 2 | yes *
### | Heading 3 | yes *
#### | Heading 4 | yes *
##### | Heading 5 | yes *
###### | Heading 6 | yes *
--- | Horizontal line | yes

* Must add a space after the characters

Focus shortcuts:

  |   | Works?
-- | -- | --
Alt + F8 | Inline toolbar (when an image, link or preview is selected) | no
Alt + F9 | Editor menu (when enabled) | no
Alt + F10 | Editor toolbar | Brings up Sound dialog
Alt + F11 | Elements path | Brings up Sound dialog

To move focus to other buttons use Tab or the arrow keys. To return focus to the editor press Escape or use one of the buttons.

[abrightclearweb]

Here is a list of the Classic Editor keyboard shortcuts for Windows with a note of which ones work in Gutenberg

Default shortcuts, Ctrl + letter:

Letter | Action | Works? | Letter | Action | Works?
-- | -- | -- | -- | -- | --
u | Underline | yes | b | Bold | yes
i | Italic | yes | x | Cut | yes
c | Copy | yes | v | Paste | yes
a | Select all | yes | z | Undo | yes
y | Redo | yes |   |   |  

Additional shortcuts, Shift + Alt + letter:

Letter | Action | Works? | Letter | Action | Works?
-- | -- | -- | -- | -- | --
1 | Heading 1 | no | 2 | Heading 2 | no
3 | Heading 3 | no | 4 | Heading 4 | no
5 | Heading 5 | no | 6 | Heading 6 | no
7 | Paragraph | no | q | Blockquote | no
d | Strikethrough | yes | x | Code | yes
c | Align center | no | r | Align right | no
l | Align left | no | j | Justify | no
u | Bulleted list | no | o | Numbered list | no
m | Insert/edit image | no | s | Remove link | yes
z | Toolbar Toggle | no | t | Insert Read More tag | no
p | Insert Page Break tag | no | w | Distraction-free writing mode | no
h | Keyboard Shortcuts | no |   |   |  

When starting a new paragraph with one of these formatting shortcuts followed by a space, the formatting will be applied automatically. Press Backspace or Escape to undo.

  |   | Works? |   |   | Works?
-- | -- | -- | -- | -- | --
* | Bulleted list | yes | 1. | Numbered list | yes
- | Bulleted list | yes | 1) | Numbered list | yes

The following formatting shortcuts are replaced when pressing Enter. Press Escape or the Undo button to undo.

  |   | Works?
-- | -- | --
> | Blockquote | yes *
## | Heading 2 | yes *
### | Heading 3 | yes *
#### | Heading 4 | yes *
##### | Heading 5 | yes *
###### | Heading 6 | yes *
--- | Horizontal line | yes

* Must add a space after the characters

Focus shortcuts:

  |   | Works?
-- | -- | --
Alt + F8 | Inline toolbar (when an image, link or preview is selected) | no
Alt + F9 | Editor menu (when enabled) | no
Alt + F10 | Editor toolbar | Triggers change block type
Alt + F11 | Elements path | no

To move focus to other buttons use Tab or the arrow keys. To return focus to the editor press Escape or use one of the buttons.

[abrightclearweb]

Just a note that the Additional shortcuts listed above

• Ctrl + Alt + letter (Mac) or
• Shift + Alt + letter(Windows)

will still work in the Classic block.

[bph]

Great work @abrightclearweb on listing all the things that work and don't work. I counted and there are still 23 shortcuts not working with Gutenberg. For power users that's a big hick-up in their work flows.

@karmatosed @jasmussen Is there ambition to be have feature parity between classic editor and Gutenberg or is that part of the user testing, and you are waiting for feedback to decide which ones make it into Gutenberg?

[jasmussen]

For the features that exist in Gutenberg that have counterparts in the classic editor, we absolutely want to make sure the shortcut keys are added. I imagine we'll ultimately end up with more keyboard shortcuts than the old editor, as there are a lot of new features. See also https://github.com/WordPress/gutenberg/pull/8316 and https://github.com/WordPress/gutenberg/pull/8279.

I imagine there are also features or flows in the classic editor that are different in Gutenberg and therefore might not make sense to port over. Not that I can think of an example right now.

[Wingo5315]

Can't you just keep the same shortcuts where possible?

[fr-laurentn]

Hello,

I noticed that the CTRL+Y shortcut used to redo an action seems to be broken (only Ctrl+Shift+Z is working). Should I open a new ticket for that?

Or is it OK to address that issue here? (I'm quite new here)

Thanks,

[talldan]

@fr-laurentn I noticed in the codebase this seems to have been done on purpose, some details in the comment above it.
https://github.com/WordPress/gutenberg/blob/0a211472bea6338dc106b87b51743524fc2f58b3/packages/editor/src/components/rich-text/index.js#L170

[afercia]

this.editor.shortcuts.remove( 'meta+y', '', 'Redo' );

Seeing this now, I'm not fully convinced;

• users are used to meta+y in addition to meta+shift+z
• on Windows, Ctrl+y is standard, while Ctrl+Shift+z doesn't make much sense
• in the classic block in Gutenberg (and in the classic editor) meta+y still works and there should be consistency across all the blocks

[fr-laurentn]

@talldan Thanks for your digging. It seems that this is not a bug.

I agree with @afercia CTRL+Y is standard to Windows users.

Should I open a new ticket?

[talldan]

@fr-laurentn a new issue would be good. Not sure that we'd want to reintroduce meta+y for Mac or Linux, but that can be open for debate on the new issue.

[fr-laurentn]

@talldan FYI here's the new issue I created: https://github.com/WordPress/gutenberg/issues/8921