cheater

cheater

cheater helps you produce cheat sheets about programming (etc.). It is a commandline program that takes in YAML and outputs an HTML page.

Writing a cheat sheet with cheater is simple:

1. Create a blank cheat sheet skeleton: cheater init -o foo.yml
2. Fill out the contents of your cheat sheet in this YAML file.
3. Give cheater your data: cheater -i foo.yml

Install with npm

npm install -g cheater # you'll need '-g' to run `cheater` wherever you want

Example output

Here's a cheat sheet made by cheater: here.

Usage

You can run cheater --help for standard usage info. But here's the process in full detail.

1. Generate cheat sheet form

Use cheater init to generate a blank cheat sheet form and print it to the console. To write it to a file foo.yml you can do cheater init -o foo.yml or cheater init > foo.yml.

cheater init can take some options:

-n, --number     (init) output n blank entries
                                             [default: 10]
-s, --simple     (init) blank entry format: instead of
                 "good" and "bad" code examples, use
                 single field "code"
                               [boolean]  [default: false]

2. Fill out cheat sheet

Open up the YAML file and have at it!

Title, Author, etc.

At the top of the file is one entry that is not like the others. Use it to title and attribute your cheat sheet. For example:

meta: True
title: An Example Cheat Sheet
subtitle: A Quick Reference on Something or Other
author: Michael Floering
homepage: http://hangtwenty.ruhoh.com/

This doesn't have to live anywhere in particular: what makes this entry special is the meta: True line.

Format of cheat sheet entries

There are two valid kinds of cheat sheet entry. This is the default format generated by cheater init, given no other arguments:

subject: Metasyntactic Variables
tip: foo bar baz
good: |
    foo bar baz
bad: |
    whatever

The other form has a single code example. You can generate a form with this simpler format using cheater init --simple:

subject: Metasyntactic Variables
tip: foo bar baz
code: |
    foo bar baz 

cheater will include any YAML files that specify at least one of the properties exemplified above. In other words, it will ignore blank entries like the one below:

subject: 
tip: 
good: |
    
bad: |

So go ahead generate a big blank YAML form with plenty of entries; you will not pollute your cheat sheet by leaving some of them blank.

You should also note that you can add a field boost to order your entries. The higher the boost, the higher up the entry will be printed. Negative values are acceptible too.

subject: Metasyntactic Variables
tip: foo bar baz
good: |
    foo bar baz
bad: |
    whatever
boost: 1000 # push it to the top of the heap

Note that this is the only ordering principle observed by cheater. The vertical order of the entries in the YAML file(s) is disregarded.

Multiple files? No problem

If you find your data file is getting too long to be manageable, go ahead and split it into multiple YAML files. cheater can take a directory as its -i/--in argument: cheater -i foo/.

3. Render cheat sheet using Jade templates

Now you can run cheater like this:

cheater -i foo.yml

It will write the rendered cheat sheet to the console. You can write the rendered cheat sheet to a file bar.html like this:

cheater -i foo.yml -o foo.html

Or this:

cheater -i foo.yml > foo.html

Finally, note that there is a non-required option -t/--templates available. You can use this to point cheater at your own directory of (jade) templates. See the templates/ folder in this repository for the expected format; if you want to customize the templates you should duplicate the templates/ directory and tweak them as needed.

Self-contained - with one exception

A cheat sheet output by cheater is self-contained except for its stylesheet, which is Twitter Bootstrap loaded from BootstrapCDN.

If you want it to be entirely self-contained (i.e. for offline use), you can edit the outputted HTML to suit your needs - or for a more maintainable solution, feed cheater some altered templates that suit your needs perfectly.

What problem does this solve?

Word processors get me down. I hate using them when they are not absolutely appropriate (such as academic papers and other formal miscellany). The chrome, sluggishness, or monetary cost of some word processors interferes with producing simple content like a cheat sheet. If the document is generic enough to use a template, I'd rather stay out of word processor land (I'm not a fan of the templating capabilities in OpenOffice, Word, or Google Docs.)

I'll bet I'm not the only one who appreciates a good cheat sheet, but doesn't want to deal with writing one in a word processor. This utility will allow you to make cheat sheets with less wasted time. Hopefully, that means you'll also make the cheat sheets you'd otherwise never get around to making.

License

MIT