Wercing with better Markdown

Change the Markdown parser used by the Werc rc shell-based web framework

For a while now, I’ve been running a few sites on werc, the “sane web anti-framework.” While it’s a very nice, minimal, and visually attractive setup, I’ve run into a few problems, one being the default markdown processor. While there isn’t really a problem with the default markdown rendering script, it lacks several popular features of GitHub’s markdown implementation, which many take for granted. One such feature is the ability to specify blocks of code. Werc’s documentation isn’t very thorough, but I doubt it will ever be improved (RIP Uriel). After a bit of digging around, I found that werc has an option to specify a different markdown renderer (actually, in theory, it is formatter-agnostic and doesn’t require markdown specifically) in the main configuration for a werc instance, in $werc/etc/initrc.local.

formatter=(fltr_cache markdown.pl)

This specifies markdown.pl, which is in $werc/bin/contrib. Werc will run the executable specified, passing the markdown file to be rendered as an argument.

The markdown processor I’d like to use is called Blackfriday. It’s a Go library with several extensions and a wide array of possible configuration options. Since Werc instances are often executed through cgd, Go is likely already on the server. Since the package is a library, a simple executable has to be made.

First, grab the Blackfriday package:

$ go get -u github.com/russross/blackfriday

The program to be made is very simple. All it does is read the file specified as an argument, run it through the markdown processor, and output the rendered html. The library has several extensions, the use of which won’t be covered here. The example just enables the library with a set of sane defaults. Save the following as a go file:

package main

import (
        "io/ioutil"
        "os"
        "github.com/russross/blackfriday"
)

func main() {
        input, _ := ioutil.ReadFile(os.Args[1])
        out := os.Stdout
        out.Write(blackfriday.MarkdownCommon(input))
}

If you’d like to test it, you can run the following, which should output html rendered from testfile.md:

$ go run md2html.go testfile.md

Build and place the executable in the proper directory:

$ go build md2html.go

$ mv md2html $werc/bin/contrib

After that, you should be all set. The code included here is just a starting point and can be modified based on your needs.

~a