Keys extension¶

This extension is meant to mimic the python markdown extension, pymdownx.keys. It provides an alternative implementation to Sphinx’ kbd role.

It simply adds a role to invoke inline usage of keyboard keys with custom CSS provided by the sphinx-immaterial theme.

kbd[class^="key-"] {
  background-color: var(--md-typeset-kbd-color);
  border-radius: 0.1rem;
  box-shadow: 0 0.1rem 0 0.05rem var(--md-typeset-kbd-border-color), 0 0.1rem 0 var(--md-typeset-kbd-border-color), 0 -0.1rem 0.2rem var(--md-typeset-kbd-accent-color) inset;
  color: var(--md-default-fg-color);
  display: inline-block;
  font-size: 0.75em;
  padding: 0 0.6666666667em;
  vertical-align: text-top;
  word-break: break-word;
  font-feature-settings: "kern";
  font-family: var(--md-code-font-family);
}

.keys span {
  color: var(--md-default-fg-color--light);
  padding: 0 0.2em;
}

Markdown extension pre-requisite¶

This pre-requisite does not mean Markdown support is enabled. However, this extension does import the pymdownx.keymap_db module to use for the keys_map option’s defaults.

To use this extension, the pymdown-extensions package needs to be installed. You can either add it as a dependency directly, or depend on the keys optional feature of this package:

python -m pip install sphinx-immaterial[keys]

And be sure to include the extension in your conf.py file.

extensions = ["sphinx_immaterial.kbd_keys"]

Keys extension role¶

:keys:¶

The value of this role is interpreted as a keyboard key name. Each role invocation can describe multiple keys pressed simultaneously using the keys_separator.

:keys:`ctrl+alt+tab`

:keys:`caps-lock`, :keys:`left-cmd+shift+a`, :keys:`backspace`

Ctrl+Alt+Tab

Caps Lock, Left Command+Shift+A, Backspace

Keys extension configuration¶

These variables can be used to control the keys role behavior from the Sphinx project’s conf.py file.

keys_strict : bool = False¶

The containing span element can strictly follow HTML5 specifications by using the kbd tag instead of a span tag.

The sphinx-immaterial theme does not adhere to the HTML5 strictness, therefore this bool option is disabled (False) by default.

keys_class : str = 'keys'¶

The class attribute str value used in the containing span element. Defaults to "keys".

Only change this if needed for your theme. The sphinx-immaterial theme is configured to use the default value.

keys_separator : str = '+'¶

The str value used as the delimiter between keys. Defaults to "+".

Changing this also requires changing the text provided to the keys role.

keys_map : dict = {}¶

An additional dict where key: value pairs consist of:

key	value
aliased key-name inputs (preferably a CSS friendly name)	displayed output str

By default the english mappings are included from the pymdownx package.

See also

The tables in pymdownx.keys docs in Extending/Modifying Key-Map Index.

conf.py CSS code rST code

Define the key name and give it a str value to display.

In our case, “Awesome Key” will be shown for :keys:`my-special-key`.

#
# optional key_map for example purposes
keys_map = {"my-special-key": "Awesome Key", "git": ""}

Remember to prepend key- to whatever the keys_map key was. In our case, my-special-key turns into key-my-special-key.

.md-typeset kbd.key-my-special-key,
.md-typeset kbd.key-git {
  color: var(--md-primary-fg-color);
  background: var(--md-accent-bg-color);
}

.md-typeset kbd.key-git::before {
  content: "██";
  -webkit-mask-image: var(--si-icon--fontawesome_brands_git);
  -webkit-mask-repeat: no-repeat;
  mask-image: var(--si-icon--fontawesome_brands_git);
  mask-repeat: no-repeat;
}

.md-typeset kbd.key-my-special-key:hover,
.md-typeset kbd.key-git:hover {
  color: var(--md-accent-fg-color);
}

Specify the key using a known name in the keys_map index.

In our case, my-special-key to fetch the display text from keys_map.

:keys:`my-special-key` + :keys:`git` = :keys:`git+my-special-key`

Awesome Key + = +Awesome Key

Use of spaces in a key name will result in CSS class that has hyphens instead of spaces in a lower case form of the given text. Therefore, entering My Special Key ignores the keys_map but still uses the key-my-special-key CSS class.

:keys:`My Special Key` + :keys:`Git` = :keys:`Git+My Special Key`

My Special Key + = +My Special Key