What is a good style for documenting OS X hotkeys on web with markdown?
I often need to give instructions on using OS X hotkeys in documentation. I write it in markdown, usually on GitHub pages and sometimes on StackExchange. The keys are formatted with <kbd>key</kbd>
= key.
In OS X interfaces the keys are usually listed together, with no spaces between. But OS X uses a well-readable font, so the string looks pretty.
But when rendered on a website, symbols don't always look good. So there are two options: to either write all keys in one tag, or each in a separate tag
Option 1.
* <kbd>⌥\</kbd> = `«`
* <kbd>⌥⇧\</kbd> = `»`
Resulting in
-
⌥\ =
«
-
⌥⇧\ =
»
Option 2
* <kbd>⌥</kbd><kbd>\</kbd> = `«`
* <kbd>⌥</kbd><kbd>⇧</kbd><kbd>\</kbd> = `»`
Resulting in
-
⌥\ =
«
-
⌥⇧\ =
»
Which is best? Should I maybe add +
symbols in between? (Which looks like a Windows-style to me).
Option 2a
-
⌥ + \ =
«
-
⌥ + ⇧ + \ =
»
Solution 1:
I'm not sure it's set in stone anywhere, but the convention for Ask Different seems to be along the lines of
<kbd> Cmd ⌘ </kbd> <kbd> Ctrl ⌃ </kbd> <kbd> Opt ⌥ </kbd> <kbd> Shift ⇧ </kbd> <kbd> T </kbd>
Cmd ⌘ Ctrl ⌃ Opt ⌥ Shift ⇧ T
giving the abbreviated name & key symbol, no + between
It's not as tidy as the Apple way, admittedly.
I'm not certain for 'key equivalents' but maybe
Opt ⌥ Shift ⇧ \ = »
as your option 2.
BTW, I use System Prefs > Keyboard > Text to generate these quickly in Stack Exchange
(which apparently only works in Safari, not Firefox or Chrome, see Replace text with predefined value in browser)