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 &lt;kbd&gt;key&lt;/kbd&gt; = 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.

* &lt;kbd&gt;⌥\&lt;/kbd&gt; = `«`
* &lt;kbd&gt;⌥⇧\&lt;/kbd&gt; = `»`


Resulting in


⌥\ = «
⌥⇧\ = »


Option 2

* &lt;kbd&gt;⌥&lt;/kbd&gt;&lt;kbd&gt;\&lt;/kbd&gt; = `«`
* &lt;kbd&gt;⌥&lt;/kbd&gt;&lt;kbd&gt;⇧&lt;/kbd&gt;&lt;kbd&gt;\&lt;/kbd&gt; = `»`


Resulting in


⌥\ = «
⌥⇧\ = »


Which is best? Should I maybe add + symbols in between? (Which looks like a Windows-style to me).

Option 2a


⌥ + \ = «
⌥ + ⇧ + \ = »
I'm not sure it's set in stone anywhere, but the convention for Ask Different seems to be along the lines of

&lt;kbd&gt; Cmd ⌘ &lt;/kbd&gt; &lt;kbd&gt; Ctrl ⌃ &lt;/kbd&gt;  &lt;kbd&gt; Opt ⌥ &lt;/kbd&gt; &lt;kbd&gt; Shift ⇧ &lt;/kbd&gt; &lt;kbd&gt; T &lt;/kbd&gt;
 Cmd ⌘   Ctrl ⌃    Opt ⌥   Shift ⇧   T  

giving the abbreviated name &amp; 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)