In the process of blogging here, as well as writing extensive documentation for my own apps, I end up writing about keyboard combinations a lot. Over the years I’ve made this easier on myself in various ways, but I think I’ve finally perfected a Jekyll plugin to make the process simple and the results consistent across my sites. I’m calling it, not too cleverly, “kbd.”
A few years back I wrote about Apple’s style guide for documenting keyboard commands. Among others, there are rules about in what order modifier keys should be presented, capitalization, and when to use hyphens versus plus signs to combine keys. Kbd handles all of that automatically.
The plugin adds a Liquid tag that lets you specify a keyboard shortcut or combination in any number of ways, in any order, minimizing the amount of time you have to think about it. You can use key binding modifier symbols (like @C), their names (Cmd-C), or actual unicode symbols (⌘C), and you can spell out the name of any key such as “escape” or “home”. You can put the modifiers in any order. You don’t have to think about whether you should use the top or bottom character on two-symbol keys like the “/?” key. The plugin will automatically output consistent, correct (according to Apple) results across your entire blog or documentation project. I currently have it in action on the Bunch site, and will be updating the Marked documentation to use it soon.
You can configure it to use symbols or spell out the key names. Apple suggests that when using graphical keys, they be combined with “+”, e.g. ⌘+C. This is only if the keys presented look like actual keyboard keys. When just displaying symbols and a character, there’s no need for the +, so it’s disabled by default, but you can enable it with use_plus_sign: true in your config. See the README for all of the options.
Any of the following will give you the same result:
{% kbd @$h %}
{% kbd $@H %}
{% kbd ⇧⌘H %}
{% kbd cmd-shift-h %}
{% kbd shift command H %}It will always output the modifiers in order, and capitalize the primary key (h above). And if you enter {% kbd cmd-? } or {% kbd cmd-shift-/ %}, both will output ⇧⌘?, as per Apple’s guidelines.
The plugin also outputs plenty of markup to make styling easy, but it’s semantic and compatible with screen readers and other accessibility tools. It even includes a spelled-out version of the combination as a title attribute on the container span so that hovering over the combo shows the full version in a tooltip.
I included the styling I’m using in the plugin’s directory in the repo (in Sass format). The markup is easy to style with any CSS, though:
<span class="keycombo" title="Control-Option-Command-R">
<kbd class="mod">⌃</kbd><kbd class="mod">⌥</kbd><kbd class="mod">⌘</kbd><kbd class="key">R</kbd>
</span>As an example, here are some screenshots from the Bunch keyboard shortcuts documentation with various plugin settings.
With symbols only, plus signs not enabled:
Symbols with plus signs enabled:
With symbols disabled:
One of the coolest things about using this plugin is that if you ever change your preferences for how keyboard shortcuts are displayed, just make a change in your _config.yml and every key combo on your site will adapt to the new style. Consistency! This will be harder to attain on this blog, as I’ve been writing here since 2012 and have not been consistent in my formatting. But from here on out…
You can find the plugin in my JekyllPlugins repository. Just drop it into your Jekyll plugins folder. It works great with Just The Docs, and should be compatible with any GitHub Pages site using GitHub actions to allow plugins.
