Keyboard Keys

The keyboard keys extension allows you to display keyboard shortcuts and key combinations in a visually appealing and semantically correct way.

Overview

Keyboard keys provide:

• Visual key styling - Realistic keyboard key appearance
• Key combinations - Display complex shortcuts clearly
• Cross-platform support - Show platform-specific keys
• Semantic markup - Proper <kbd> HTML elements
• Consistent formatting - Unified appearance across docs
• Accessibility - Screen reader friendly

Configuration

Enable keyboard keys in mkdocs.yml:

markdown_extensions:
  - pymdownx.keys

Additional Configuration

For advanced key mappings:

markdown_extensions:
  - pymdownx.keys:
      separator: "\uff0b"  # Custom separator character

Basic Usage

Single Keys

Use ++key++ to create keyboard keys:

Press ++enter++ to submit the form.
Press ++escape++ to cancel.
Press ++space++ to pause playback.

Result:

Press Enter to submit the form. Press Esc to cancel. Press Space to pause playback.

Key Combinations

Combine multiple keys with +:

++ctrl+c++ - Copy
++ctrl+v++ - Paste
++ctrl+z++ - Undo
++ctrl+shift+i++ - Open developer tools

Result:

Ctrl+C - Copy Ctrl+V - Paste Ctrl+Z - Undo Ctrl+Shift+I - Open developer tools

Key Reference

Modifier Keys

Key	Windows/Linux	macOS
Ctrl	Control	Control
Alt	Alt	Option (⌥)
Shift	Shift	Shift
Cmd	Windows	Command (⌘)
Meta	Windows	Command (⌘)

Function Keys

++f1++ through ++f12++ - Function keys
++fn+f1++ - Function key with modifier

Result:

F1 through F12 - Function keys Fn+F1 - Function key with modifier

Navigation Keys

++arrow-up++ ++arrow-down++ ++arrow-left++ ++arrow-right++ - Arrow keys
++page-up++ ++page-down++ - Page navigation
++home++ ++end++ - Line navigation
++tab++ ++enter++ - Common actions

Result:

Up Down Left Right - Arrow keys Page Up Page Down - Page navigation Home End - Line navigation Tab Enter - Common actions

Special Keys

++backspace++ - Delete backwards
++delete++ - Delete forwards
++insert++ - Insert mode
++print-screen++ - Screenshot
++scroll-lock++ - Scroll lock
++pause++ - Pause/Break
++caps-lock++ - Caps lock
++num-lock++ - Number lock
++menu++ - Context menu

Result:

Backspace - Delete backwards Del - Delete forwards Ins - Insert mode Print Screen - Screenshot Scroll Lock - Scroll lock Pause - Pause/Break Caps Lock - Caps lock Num Lock - Number lock Menu - Context menu

Platform-Specific Keys

Windows Shortcuts

Action	Shortcut	Description
Copy	Ctrl+C	Copy selected content
Cut	Ctrl+X	Cut selected content
Paste	Ctrl+V	Paste from clipboard
Select All	Ctrl+A	Select all content
Find	Ctrl+F	Open find dialog
Save	Ctrl+S	Save current document
New Tab	Ctrl+T	Open new tab
Close Tab	Ctrl+W	Close current tab

macOS Shortcuts

Action	Shortcut	Description
Copy	Cmd+C	Copy selected content
Cut	Cmd+X	Cut selected content
Paste	Cmd+V	Paste from clipboard
Select All	Cmd+A	Select all content
Find	Cmd+F	Open find dialog
Save	Cmd+S	Save current document
New Tab	Cmd+T	Open new tab
Close Tab	Cmd+W	Close current tab

Cross-Platform Display

Save your work:
- Windows/Linux: ++ctrl+s++
- macOS: ++cmd+s++

Open preferences:
- Windows/Linux: ++ctrl+comma++
- macOS: ++cmd+comma++

Result:

Save your work: - Windows/Linux: Ctrl+S - macOS: Cmd+S

Open preferences: - Windows/Linux: Ctrl+, - macOS: Cmd+,

Advanced Usage

Complex Combinations

++ctrl+alt+delete++ - Windows security options
++cmd+option+escape++ - macOS force quit
++ctrl+shift+escape++ - Task Manager
++cmd+space++ - Spotlight search

Result:

Ctrl+Alt+Del - Windows security options Cmd+Option+Esc - macOS force quit Ctrl+Shift+Esc - Task Manager Cmd+Space - Spotlight search

Sequences

Show key sequences for multi-step shortcuts:

In Vim:
1. Press ++escape++ to enter normal mode
2. Type ++colon+w+q++ to save and quit
3. Or ++colon+q+exclamation++ to quit without saving

Result:

In Vim: 1. Press Esc to enter normal mode 2. Type :+W+Q to save and quit 3. Or :+Q+! to quit without saving

Gaming Keys

Movement: ++w++ ++a++ ++s++ ++d++
Jump: ++space++
Crouch: ++ctrl++
Sprint: ++shift++
Interact: ++e++

Result:

Movement: W A S D Jump: Space Crouch: Ctrl Sprint: Shift Interact: E

Styling

Custom CSS

/* Custom keyboard key styling */
.md-typeset kbd {
    display: inline-block;
    padding: 0.2em 0.4em;
    font-size: 0.85em;
    font-weight: 700;
    line-height: 1;
    color: var(--md-default-fg-color);
    vertical-align: middle;
    background-color: var(--md-code-bg-color);
    border: 1px solid var(--md-default-fg-color--lighter);
    border-radius: 0.2rem;
    box-shadow: 0 2px 0 1px var(--md-default-fg-color--lightest);
}

/* Hover effect */
.md-typeset kbd:hover {
    background-color: var(--md-accent-bg-color);
    transform: translateY(1px);
    box-shadow: 0 1px 0 1px var(--md-default-fg-color--lightest);
}

/* Dark theme adjustments */
[data-md-color-scheme="slate"] .md-typeset kbd {
    background-color: var(--md-code-bg-color);
    border-color: var(--md-default-fg-color--lighter);
}

Size Variations

/* Large keys */
.md-typeset kbd.key-large {
    padding: 0.4em 0.8em;
    font-size: 1em;
}

/* Small keys */
.md-typeset kbd.key-small {
    padding: 0.1em 0.3em;
    font-size: 0.75em;
}

Practical Examples

Editor Shortcuts

VS Code Shortcuts

File Operations: - New File: Ctrl+N / Cmd+N - Open File: Ctrl+O / Cmd+O - Save: Ctrl+S / Cmd+S - Save As: Ctrl+Shift+S / Cmd+Shift+S

Editing: - Find: Ctrl+F / Cmd+F - Replace: Ctrl+H / Cmd+Option+F - Multi-cursor: ++alt+click++ / ++option+click++ - Comment Line: Ctrl+/ / Cmd+/

Terminal Commands

## Common Terminal Shortcuts

- Clear screen: ++ctrl+l++
- Cancel command: ++ctrl+c++
- Exit terminal: ++ctrl+d++
- Search history: ++ctrl+r++
- Move to line start: ++ctrl+a++
- Move to line end: ++ctrl+e++
- Delete word: ++ctrl+w++
- Paste: ++shift+insert++ or ++ctrl+shift+v++

Application Shortcuts

Application	Action	Windows	macOS
Browser	New Tab	Ctrl+T	Cmd+T
Browser	Refresh	F5 or Ctrl+R	Cmd+R
Browser	Dev Tools	F12	Cmd+Option+I
Slack	Quick Switcher	Ctrl+K	Cmd+K
Discord	Toggle Mute	Ctrl+Shift+M	Cmd+Shift+M

Accessibility

Screen Reader Considerations

Keyboard keys are wrapped in semantic <kbd> elements:

<kbd>Ctrl</kbd> + <kbd>C</kbd>

Screen readers announce these appropriately as keyboard keys.

Alternative Text

For complex shortcuts, provide text descriptions:

Copy text with ++ctrl+c++ (Control + C)

Integration Examples

In Tables

Feature	Shortcut	Description
Bold	Ctrl+B	Make text bold
Italic	Ctrl+I	Make text italic
Underline	Ctrl+U	Underline text
Link	Ctrl+K	Insert hyperlink

In Admonitions

Productivity Tip

Use Alt+Tab to quickly switch between applications.

Hold Shift while pressing Tab to reverse direction.

In Lists

Text Navigation Shortcuts: - Ctrl+Right - Move by word - Ctrl+Left - Move by word (backwards) - Ctrl+Home - Go to document start - Ctrl+End - Go to document end - ++shift+arrow-keys++ - Select text

In Code Comments

# Press Ctrl+Space for autocomplete
def calculate_sum(a, b):
    # Use Ctrl+/ to comment/uncomment lines
    return a + b  # Press F2 to rename symbol

Common Patterns

Step-by-Step Instructions

1. Press Cmd+Space to open Spotlight
2. Type "terminal" and press Enter
3. Navigate with Up and Down
4. Use Tab for command completion
5. Press Ctrl+C to cancel if needed

Shortcut Reference Card

Essential Shortcuts

	Windows	macOS
Copy	Ctrl+C	Cmd+C
Cut	Ctrl+X	Cmd+X
Paste	Ctrl+V	Cmd+V
Undo	Ctrl+Z	Cmd+Z
Redo	Ctrl+Y	Cmd+Shift+Z
Find	Ctrl+F	Cmd+F
Save	Ctrl+S	Cmd+S
Print	Ctrl+P	Cmd+P

Best Practices

1. Consistency

Always use the same format for the same key:

✅ Good: Always use ++enter++
❌ Bad: Mix of ++enter++, ++return++, "Enter key"

2. Platform Awareness

Specify platform when shortcuts differ:

✅ Good:
Windows: ++ctrl+c++
macOS: ++cmd+c++

❌ Bad:
Press Ctrl+C or Cmd+C

3. Context

Provide context for shortcuts:

✅ Good:
To save your document, press ++ctrl+s++

❌ Bad:
++ctrl+s++

4. Grouping

Group related shortcuts:

✅ Good:
**File Operations:**
- New: ++ctrl+n++
- Open: ++ctrl+o++
- Save: ++ctrl+s++

See Also

• PyMdown Extensions - Keys
• HTML <kbd> Element
• Keyboard Shortcuts Best Practices