Keys

Overview

Keys is an extension to make entering and styling keyboard key presses easier. Syntactically, Keys is built around the + symbol. A key or combination of key presses is surrounded by ++ with each key press separated with a single +.

++ctrl+alt+delete++

The Keys extension can be included in Python Markdown by using the following:

import markdown
md = markdown.Markdown(extensions=['pymdownx.keys'])

Formatting

By default, Keys outputs keys in the form:

<span class="keys">
  <kbd class="key-ctrl">Ctrl</kbd>
  <span>+</span>
  <kbd class="key-alt">Alt</kbd>
  <span>+</span>
  <kbd class="key-delete">Delete</kbd>
</span>

Separator spans will be omitted if a separator is not provided via the options.

Notice the wrapper span has the class keys applied to it. This is so you can target it or the elements under it with CSS. Each recognized key has its own special key class assigned to it in the form key-<key name>. These individual key classes are great if you want to show a special modifier key symbol before the key text (which is done in this documentation).

The wrapper keys class can be customized with options, and the individual key classes are generated from the key-map index.

separator spans will be omitted if a separator is not provided via the options)

Custom Keys

If you would like to generate a key which isn't in the key index, you can extend the key map via a special option. But if you don't need a key with a special class generated, or you need a way to quickly enter a one time, arbitrary key, you can just insert it directly, instead of specifying the key's name, by quoting the content displayed instead of a key name. You can also enter HTML entities if desired.

++ctrl+alt+"My Special Key"++

++cmd+alt+"Ü"++

Strict KBD Output

According to HTML5 spec on kbd, a literal key input, is represented by a kbd wrapped in another kbd:

<kbd class="keys">
  <kbd class="key-ctrl">Ctrl</kbd>
  <span>+</span>
  <kbd class="key-alt">Alt</kbd>
  <span>+</span>
  <kbd class="key-delete">Delete</kbd>
</kbd>

This is not how many people traditionally use kbds for key inputs, but if you are a stickler for rules, you can enable the strict option to use a more "proper" format.

Key-Map Index

By default, Keys provides a key-map index for English US keyboards. The key-map index is a dictionary that provides all the supported key names along with their corresponding display text. There is also a separate alias dictionary which maps some aliases to entries in the key-map index.

Extending/Modifying Key-Map Index

If you want to add additional keys, or override text of existing keys, you can feed in your keys via the key_map option. The key_map parameter takes a simple dictionary with key names that are represented by lowercase alphanumeric characters and hyphens (-). The values of the dictionary represent the text that is displayed for the key in the HTML output.

So if you wanted to add a custom key, you could do this: {"custom": "Custom Key"}. If you wanted to override the output of the option key and change it from Option to Opt, you could do this: {"option": "Opt"}.

Alphanumeric and Space Keys

Punctuation Keys

Navigation Keys

Editing Keys

Action Keys

Numeric Keypad Keys

Modifier keys

Function keys

Extra Keys

Mouse

Options