Cheaters 2.1

I spent some time over the weekend adding a few things to Cheaters that I’d been meaning to for a while.

Metadata

First is the addition of metadata in cheatsheets. It’s not required on any sheet, but it opens up some possibilities for easier customization per sheet. The data is added in a JSON format, with %%%END as separator between the meta block and the rest of the sheet. In a Markdown file, this can go right at the top, e.g.

{
    "id": "bt_js",
    "style": "css/JavaScript.css",
    "layout": "multicolumn"
}
%%%END
### Beginning of the cheat sheet

In HTML files this gets wrapped in an HTML comment:

<!--
{
    "id": "bt_js",
    "style": "css/JavaScript.css",
    "layout": "multicolumn"
}
%%%END-->

Right now only a few keys are used, but it will be easy to add more (including attribution keys and external links). Unused keys are just ignored.

The current keys are id (just applies the specified id to the body element), style (allows an additional CSS stylesheet to be included), and layout. Layout can be any value but the only one that actually changes anything at the moment is multicolumn. If "layout": "multicolumn" is set in the metadata, the whole thing gets split into a horizontal layout. For sheets with sections broken up by h3/h4 elements and without a lot of tables, this actually makes a more easily-scanned page (I think). Find more details in the documentation.

Custom stylesheets

Because I kept finding myself adding HTML ids and custom styles for certain cheatsheets that had different layouts, I decided that the style metadata key would allow the inclusion of external CSS files. These are loaded when a cheatsheet is opened, and removed when changing cheatsheets. Thus you can just restyle default elements without needing to namespace them, but you can always use the id meta to allow more specific targeting of elements.

I’d started out naming stylesheets by their associated cheatsheet (e.g. Markdown.css), but realized they should be more generic (e.g. h4dark.css) so they could be used more universally. It’s not a perfect system, and it still needs some cleaning up, but it’s definitely allowing more flexibility.

Table of Contents

If you’ve made use of Cheater’s “Fast Switcher,” you’ll probably appreciate this next bit. It’s pretty much the reason I started hacking on Cheaters this weekend.

When a cheat sheet is longer than fits in view (which is most of them), navigating can be a bit tedious. There’s the header navigation with , and . (comma and period), but I wanted a way to jump to a specific section. Thus, a table of contents was needed.

Typing “t” will pop it up. It’s generated from headers 1-4, plus tables with captions or th (whichever has an id attribute). For most sheets, this generates a workable navigation structure. A type-ahead filter field is automatically focused when it opens. Typing performs a fuzzy search on the available titles, and if it narrows down to just one, hitting enter will immediately jump to that section, closing the TOC in the process.

In Fluid’s menu bar mode, the Tab and Escape keys behave differently from most browsers, so tabbing from the filter input to the menu items doesn’t work. If you hit enter the first one is selected, in which case you can hit enter again (but not tab to the next). For now, this circumstance requires a mouse click if there is more than one result.

Escape will close the TOC popup at any time, but in Fluid pinned mode that will also dismiss the whole window, so the current solution is to click anywhere off of the TOC to dismiss it. A keyboard solution would be nice, but not in the cards quite yet.

A Quick and Dirty Server

Cheaters requires a web server to run locally. If editing your Apache setup or running MAMP isn’t your cup of tea, I’ve also included a tiny little script called cheat.sh in the cheaters folder. That will launch Python’s SimpleHTTPServer in that directory with an address of http://localhost:4000, which you can then plug into Fluid or Automator (or a web browser).

If you want to set this up to run automatically with launchd, it would probably be wise to add a cd /path/to/your/cheaters/folder/ line in before the python command and set it up with a KeepAlive key.

General Cleanup

As part of the changes to the styling setup, I cleaned up all of the existing cheatsheets in the repository. This includes some changes to ones contributed by other people. Be aware of this if you’re updating a Cheaters install with any of your own customizations.

Just a Reminder…

Don’t forget:

• “f” for Fast Switcher
• Search shortcuts
• Vim navigation (j/k, u/d, G/gg, h/l to switch sheets)
• . and , to navigate by sections
• Cheaters.switchTo() command

Download

You can download Cheaters below, but I do recommend setting it up by cloning the GitHub repository if that’s something you’re comfortable doing.