3

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.

enter image description here

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

  • ⌥ + \ = «
  • ⌥ + ⇧ + \ = »
Nick Volynkin
  • 167
  • 1
  • 1
  • 14

1 Answers1

5

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)

enter image description here

Community
  • 1
Tetsujin
  • 106,445
  • 25
  • 181
  • 313
  • What is the SE? – Nick Volynkin Jul 05 '15 at 09:16
  • SE = Stack Exchange - the site in its entirety. For running order, I'm not actually certain. I've always used the order in which I would say them, or was told them when I first started, 25 years ago.. Cmd, ctrl, opt,shift - which echoes how Apple do it, but with cmd at the front rather than the back. I'm guessing they use that order as it would appear to be the symbol they line up to, but we don't have that option. – Tetsujin Jul 05 '15 at 09:25
  • thank you! I've just set up a replacement, and it works in native OS X apps, but not in others, e.g. the Firefox. Should I use Safari for this feature to work? – Nick Volynkin Jul 05 '15 at 09:32
  • oh, just found it here. http://apple.stackexchange.com/questions/88870/replace-text-with-predefined-value-in-browser – Nick Volynkin Jul 05 '15 at 09:33
  • Ah - I hadn't thought of that. I've never used Firefox, but I just tested & it doesn't work in Chrome either. Seems to be only Safari recognises it correctly. – Tetsujin Jul 05 '15 at 09:34