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:

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:

• Latest release download

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:

• ttscoff/kbd on GitHub

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Apex can render Markdown to the terminal (-t terminal or -t terminal256) with ANSI colors and themes. As of 0.1.100, it can also draw images inline when stdout is a real TTY: your ![alt](path-or-url) images show up as actual graphics instead of only link-style text.

What actually draws the image

Apex does not embed a rasterizer. It looks for an external viewer on your PATH, in this order:

1. imgcat (iTerm2-style inline images)
2. chafa
3. viu
4. catimg

The first one that exists wins. If none are found, or something fails, or you are piping output (not a TTY), you get the same link-style fallback as a normal terminal link: styled alt text plus the URL in parentheses.

Remote http:// and https:// images are downloaded with curl (temp file under TMPDIR or /tmp, then deleted). There is a size cap and timeout so runaway downloads do not blow up your session.

Flags and metadata

• --no-terminal-images turns inline rendering off entirely (always link-style).
• --terminal-image-width N sets the maximum width in character cells (default 50). This is separate from --width, which wraps prose.

You can also set terminal.inline_images / terminal_inline_images and terminal.image_width / terminal_image_width in metadata or config.

Installing the viewers (macOS)

iTerm2 ships imgcat on your PATH when you use its utilities, so you may already have the first choice. The others are a quick Homebrew install:

# Optional: pick one or more (Apex uses the first available on PATH)
brew install chafa viu catimg

On Linux, use your distro packages or the projects’ install notes; the same binary names apply.

Other stuff

Since 0.1.95, this line of releases also landed a bunch of other work. Highlights:

• CSV/TSV includes with custom delimiters ({delimiter=X} or {;}) across iA Writer, Marked, and MultiMarkdown include styles.
• Metadata handling improved: mode-aware extraction, better MultiMarkdown / Unified / Kramdown behavior, and standalone HTML now emits generic metadata as proper <meta name="..."> tags.
• MultiMarkdown includes and transclusions accept embedded delimiter overrides without breaking on braces in paths.
• Swift tooling: ApexC exposes the C API for SwiftPM, collision fixes for apex_* symbols, and NSString.defaultApexOptions() for plugins that need low-level options.
• HTML output shape: --to xhtml serializes void elements in XML style (<br />, self-closing meta/link, and so on). --to strict-xhtml goes further for full documents: with --standalone it adds polyglot XHTML scaffolding (XML declaration, XHTML namespace, application/xhtml+xml metadata). Use one or the other; they target different strictness levels.
• Homebrew formula updates for recent releases.

If you want the full blow-by-blow, see the project changelog on GitHub.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.