Creating shortcuts for Mac symbols in HTML

I use a fairly complex build system for the Marked 2 help documents that get used on both the website and in the internal help. Among the many features I’ve added over time is the ability to use named shortcuts for Mac symbols — Command, Shift, the Apple Menu, etc. — and have them replaced with HTML entities at compile time. Since it took a bit to put together the whole list, I thought I’d share it for anyone who faces a similar task.

What the script below does is look for {{name}} tags (liquid/mustache-style) in the Markdown text that I use for the help files. It could be {{cmd}} or {{home}} or just about any key that has a symbol. I even added one for the {{gear}} menu on Marked’s preview window.

The concept is really simple: find anything surrounded by double curly brackets ({{}}) and check to see if it matches anything in the symbols list. If it does, return the HTML entity, if not, just return the original string.

It’s written in Ruby, but it could easily be ported to Python, Node, or whatever your build system calls for. I’m just putting it out there as an idea you can implement in whatever way is useful.

Here’s the snippet, I’ll put some examples below.

class String
  def replace_with_entity
    case self.downcase
    when /apple/
      ""
    when /(comm(and)?|cmd|clover)/
      "⌘"
    when /(cont(rol)?|ctl|ctrl)/
      "⌃"
    when /(opt(ion)?|alt)/
      "⌥"
    when /shift/
      "⇧"
    when /tab/
      "⇥"
    when /caps(lock)?/
      "⇪"
    when /eject/
      "⏏"
    when /return/
      "⏎"
    when /enter/
      "⌤"
    when /(del(ete)?|back(space)?)/
      "⌫"
    when /fwddel(ete)?/
      "⌦"
    when /(esc(ape)?)/
      "⎋"
    when /right/
      "→"
    when /left/
      "←"
    when /up/
      "↑"
    when /down/
      "↓"
    when /pgup/
      "⇞"
    when /pgdn/
      "⇟"
    when /home/
      "↖"
    when /end/
      "↘"
    when /clear/
      "⌧"
    when /gear/
      "⚙"
    else
      "{{#{self}}}"
    end
  end

  def render
    # Replace {{insertions}}
    self.gsub(/\{\{(.*?)\}\}/) {|mtch|
      m = Regexp.last_match
      m[1].strip.replace_with_entity
    }
  end
end

Now if you have a string like {{cmd}}{{opt}}P or {{del}} or {{gear}} in your text and you run .render on it, you’ll get back entitized text.

string = "{{opt}}{{cmd}}P or {{del}} or {{gear}}"
puts string.render

gives you:

⌥⌘P or ⌫ or ⚙

which, in an HTML document displays as: ⌥⌘P or ⌫ or ⚙.

Hope it’s handy.