Dash docsets from MultiMarkdown

[Tweet]

Dash is my favorite way to reference syntax and info about dozens of programming languages, and one of my most used applications. The developer of Dash recently released “Cheatset”, a way to build your own Cheat Sheets to display in Dash as docsets, complete with indexed commands and categories.

I love Cheaters, but this is awesome. I can have all of my cheat sheets in one place without running two applications, and I can create very custom ones for things like my Moom shortcuts and keybindings. I’ll probably keep playing with Cheaters, but this is a new level. The only problem is I don’t like the verbosity of the syntax (Ruby DSL) required to generate the cheat sheets with cheatset.

I had already started a script that generated DSL input from MultiMarkdown for dasheets, and really liked the flexibility. I converted it slightly to work with Cheatset, and I think other people will appreciate it as well. It’s a procedural script with lots of potential fail points, but I haven’t run into any problems yet.

First, you need to install Cheatset. This is done with gem install cheatset. If you run into trouble, check the Cheatset issues.

Download the mmd2cheatset.rb script from GitHub and place it somewhere in your path. Make it executable with chmod a+x mmd2cheatset.rb.

Now, you just need to make a MultiMarkdown document that you can run through mmd2cheatset. The script will call cheatset on its own, so all you have to do is run mmd2cheatset.rb cheatsheet.md.

You simply fill in a few MultiMarkdown metadata headers, then build out your cheatsheets using MultiMarkdown table syntax. The headers required are:

title: MultiMarkdown to Docset
name: MMD2Docset
keyword: mmd2ds

You can optionally include a resource_folder key that points to an existing folder with additional assets. It’s not necessary, though. The keyword field, on the other hand, is vital. Trust me.

Any text after the metadata and a blank line but before the first table becomes the (optional) introductory text for the cheat sheet. Text after the last table and a horizontal rule (---) becomes the footer.

Tables must be formatted with 3 columns in this order:

| Name   | Command | Note |
| ------ | -----   | ---- |

“Name” is the action, or what will happen when the command is run. It can contain Markdown.

“Command” is the key combination that will run the command. It can be anything, but note that commas separate multiple commands. These will be surrounded with kbd tags and made to look like actual keys.

“Note” is any superfluous information. It can contain Markdown as well.

If the cheat sheet is just a list of methods or functions and related notes, leave the command cell blank. You can leave any cell blank, as long as the columns stay in the proper order.

The table must end with an identifier in square brackets:

| Previous item (same as↑ )          | CTRL-P  |      |
| Next item (same as↓ )              | CTRL-N  |      |
[Global]

This will create a category called “Global” for the commands.

You can repeat as necessary for each category of commands. There are some sample documents in the repository to show all of this.

If you build some useful MultiMarkdown versions of cheat sheets, please let me know if you want to contribute them to the repository.