Easy command line Github Flavored Markdown

[Tweet : ADN : nvALT]

I wrote a quick wrapper script for converting local Markdown files or raw text to HTML using Github Flavored Markdown. It uses the Github API, so there are no local dependencies (other than the json gem, see below). It just requires an Internet connection. Syntax highlighting and Github stylesheets are included in the output. Any syntax recognized by Github is converted, including line breaks and fenced code.

Installation

To run it, you first need to make sure you have the json gem. To install it, use gem install json (you might need sudo gem install json, depending on your setup). Once that’s installed, just save the script as flavor in your path and make it executable (chmod a+x /path/to/flavor).

I’m using the ‘gfm’ mode of the API, which includes a feature that converts “@mentions” into Github addresses. To disable these extras, change line 45 to output['mode'] = 'markdown'.

Usage

You can pass Markdown to flavor in two ways: piped to STDIN or by providing a filename.

To pipe input, just use a Unix pipe after any command that creates output on STDOUT, e.g.:

cat README.md | flavor

To pass a filename:

flavor README.md

There’s one optional argument, “-c”, which will automatically copy the output to the clipboard using pbcopy. This is just for my own convenience, you can always pipe the output to pbcopy yourself. If you include this argument along with a filename, make sure the “-c” comes before the filename on the command line (flavor -c README.md).

Unless “-c” is used, output is always to STDOUT, meaning you can easily redirect it to a file with flavor README.md > README.html. I like to use it with a utility called bcat that outputs the result directly to my browser (flavor README.html | bcat).

I built this just for testing Marked’s output against Github output, but it’s universally useful so I thought I’d share. Download the script here or skip straight to the raw version and save from there.