Suggestion: Using {kbd} role for keybindings

[melissawm]

Now that keybindings are becoming more stable, would it be a good idea to use the {kbd} role for keys in documentation? For example, using the

{kbd}`ctrl`+{kbd}`z`

syntax shows this in the rendered docs:

A few things to consider:

• This is very black 😅 we may want to style those keybindings differently
• The kbd role in both myst and sphinx may be styled differently from the rest of the literal/code rendering we have currently, so marking those keys makes it easier to change this in the future.

[psobolewskiPhD]

We discussed this yesterday in the docs meeting. I'm a big fan of this. We just need to use {kbd}`letter` for shortcuts? and this will already work?
I don't love the black, but it is contrasty. I think I'd prefer something more subtle like a black outline and light grey? But this is for the theme to take care of right?
Eitherway, I think we should add this to the Docs contribution guide.

[melissawm]

Correct on all counts - as long as we mark the key bindings with this syntax, the looks can be fixed later with some CSS on the theme side.

[jni]

@melissawm I love this, but just to clarify, does {kbd}`Ctrl+Z` not work as expected? I find it jarring to have the + in the middle, rather than in the same expression. It would be great if the theme became smart enough to start rendering shortcuts in a platform-specific way, like the theme shortcuts themselves are:

But for that to work, the modifiers and the keys should be in the same expression.

But, either way, I love the idea. ❤️

[melissawm]

Oh absolutely, we can do that! I can put in a proposal for both

1. fixes for existing content, and
2. a note in the style guide (and probably the PR template) about not forgetting to use this syntax for new shortcuts in the docs.