If you write documentation, tutorials, or notes that include keyboard shortcuts, you know how annoying consistency can be. Sometimes you want plain text like Shift-Command-K, sometimes you want nice symbolic output like ⇧⌘K, and sometimes you want HTML keycaps.

This project started as a Jekyll plugin, then became a WordPress plugin, and now I’m offering it as a CLI and Automator Actions you can use anywhere.

What the scripts do

The project ships two Ruby scripts that parse keyboard shortcut text and normalize it into consistent output, following Apple’s guidelines by default:

  • kbd.rb outputs HTML keycap markup.
  • kbd-text.rb outputs plain text shortcuts.

Both scripts accept flexible input formats, including:

  • Keybinding Symbol style: "$@k"
  • Text style: "shift cmd k"
  • Hyphenated style: "Shift-Command-k"
  • Multiple combos separated by " / "

For keybinding style:

Modifier Symbol Shortcut
Shift ⇧ $
Option ⌥ ~
Command ⌘ @
Control ⌃ ^

In practice, this means you can type shortcuts however you naturally type them, and the tool will clean and format them for you.

Download and install as Quick Actions

Grab the latest release from:

Then install:

  1. Download KBD Automator Actions.zip.
  2. Unzip it.
  3. Double-click each .workflow file.
  4. Confirm installation when macOS prompts.

After that, the actions show up as Services/Quick Actions for text handling.

Add keyboard shortcuts for the Services

Once installed, assign your own hotkeys:

  1. Open System Settings.
  2. Go to Keyboard.
  3. Click Keyboard Shortcuts.
  4. Select Services on the left.
  5. Find Text -> KBD *.
  6. Click the shortcut field on the right.
  7. Press the shortcut you want.

That is it. You now have a fast shortcut-to-formatted-shortcut pipeline available from anywhere.

Configuration

The scripts read config from:

  • ~/.config/kbd/config.yaml

You do not need to create this manually. The first time either script runs, it writes this file with default values.

Available keys under kbd::

  • use_modifier_symbols (default: true)
    • true: prefer symbols like ⌘, ⌥, ⇧
    • false: use words like Command, Option, Shift
  • use_key_symbols (default: true)
    • true: use symbolic key names where possible
    • false: use text key names
  • use_plus_sign (default: false)
    • false: combine modifier symbols with no separator (⇧⌘K)
    • true: join with + (⇧+⌘+K)

Build and release it yourself

If you want to generate or ship your own builds, the repo includes Rake tasks for:

  • building self-contained scripts
  • generating signed Automator workflows
  • packaging release zip files
  • bumping versions and publishing GitHub releases

Project link: