Moving to Wintersmith

I finally moved willkle.in to a proper static site generator: Wintersmith. I’ve been testing Wintersmith for a while, and this past week I finally ironed out the details. It took a while to port my HTML into Jade templates and to get the content flowing correctly. I stuck with GitHub Pages for hosting, and tried Wercker for automated build and deployment. There’s more I plan to do, but here’s the how and why of my progress so far.

GitHub Pages includes Jekyll out of the box. This works fine and I used it for HartfordJS.com, but I wanted something more customizable. GitHub Pages restricts custom plugins for security reasons, which is a bit limiting. I can still use GitHub Pages for free hosting, as long as I keep my build process offline or elsewhere.

Being a JavaScript/Node guy, Wintersmith was an excellent place to start. Johan Nordberg did a terrific job making it extensible, providing excellent support on GitHub and Stack Overflow. Wintersmith is actually written in CoffeeScript, though that shouldn’t matter much. I reviewed the source to figure out how things work and found the code very easy to follow. Johan made it relatively easy to extend by providing a plugin template and API documentation. There are plenty of template engines supported; I stuck with Jade, the default. Jade has HAML-like syntax, which doesn’t look anything like HTML at first glance. It can honestly be a pain to learn at first, but I’ve enjoyed the “shorthand” style of authoring HTML. Besides plugins, Wintersmith can also be customized by including other Node modules. I included Lo-Dash for util functions and Moment.js for date formatting. I could then use those libs directly in my Jade templates.

The last piece of the puzzle for me was auto-deployment. My desired workflow:

  1. Create a new Markdown file.

  2. Push that file to GitHub.

That’s it. I wanted to edit a single file and have that publish without any fuss. I love how GitHub Pages works this way for Jekyll-based sites; for publishing on Wintersmith, this is where Wercker comes in. Wercker bills itself as an “open delivery platform.” What it really does is it lets you write build scripts, hook into GitHub, and auto-build/deploy whenever you push to your repo. I found a very helpful blog post explaining step-by-step how to wire up Wintersmith with GitHub Pages. Wercker also wrote up how to publish anything to Pages. I really like how Wercker can be used for a lot more than this, like continuous integration, or anything automated. It’s free to try while in beta, so check it out.

This publishing workflow is very much a hacker’s solution. I really enjoyed piecing it together, and it’s highly extensible from here. Up next, I’m planning to rebuild my HTML & CSS on Bootstrap 3. I’m also hoping to build more on Wintersmith, more on that to come.