Node based static site generators

My first experience with node.js was following the ‘hello world’ tutorial on the front page, which I then extended to experiment with writing in Markdown and creating HTML pages on the fly. Not quite a static site generator, but a fun experiment in learning during the Mozilla Polyglot Hackathon.

I’m currently using Octopress to power this site as well as bmannconsulting.com (see my migration write up), but one of the things I’d like is the ability to not have to have access to my dev environment in order to publish pages. That is, right now I can create/edit Markdown files anywhere¹ since my blog source is in Dropbox, but to compile / publish it, I need access to a machine that has the development environment installed.

I am hoping to use a node.js-based static site generator running on Heroku or Nodejitsu to have the best of both worlds. A minimal http server to serve up the baked HTML static files, plus the ability to connect to a Dropbox folder with Markdown posts in it and bake them on demand.

My first stop was to look at the existing node.js-based static site generators. I was looking for something with the simplicity and elegance of Octopress. To me, that means simple, one file posts with included metadata plus simple, as close-to-HTML as possible templating. Here’s the list of projects I found, with a few notes on each one.

##Wintersmith

• Source Link: github.com/jnordberg/wintersmith
• Last Updated: < 1 month ago
• Pros:
  • Small, discrete code base, including plugin architecture
  • Under active development
• Cons:
  • Jade-based templates
  • Written in CoffeeScript

DocPad

• Source Link: github.com/bevry/docpad
• < 1 month ago
• Pros:
  • Does a LOT.
  • Under active development
• Cons:
  • Overkill - support for the many templating options plus using CoffeeScript makes it hard to start hacking on

##Blacksmith

• Source Link: github.com/flatiron/blacksmith
• Last Updated: ~ 2 months ago
• Pros:
  • Has a generator and a server
  • HTML-based templates
• Cons:
  • Metadata for posts in separate json file & each post in a separate folder
  • Updated: incorrectly stated Jade-based templates - actually uses HTML-based templates

Scotch

• Source Link: github.com/techwraith/scotch
• Last Updated: ~ 3 months
• Pros:
  • Comes with a redis-based cache, but can also compile to static files
• Cons:
  • Needs geddy and redis running
  • Couldn’t get it working

Wheat

• Source Link: github.com/creationix/wheat
• Last Updated: ~ 6 months
• Pros:
  • Serves files from a git repo
  • Runs the the howtonode.org website
• Cons:
  • Couldn’t get it running
  • HAML templates

Petrify

• Source Link: github.com/caolan/petrify
• Last Updated: 11 months
• Pros
  • Interesting JSON templates
• Cons:
  • Generator only
  • Couldn’t get it running (outdated “require path” syntax)

Wintersmith comes closest to being what I want. It’s maintained, works well out of the box, and has a minimal codebase. But, the double whammy of being written in CoffeeScript and using Jade-based templates by default makes it a no go. There is a plugin for Swig templates, so perhaps I’ll keep experimenting with it.

After all of that, none of the existing node.js-based SSGs seem like a great fit for adding Dropbox support for. So, I’m going to attempt to write one myself. To recap what I’m looking for:

• Site generator plus simple server for local previews + easy PaaS hosting
• Minimal, close-to-HTML-based templating
• Single file posts that include metadata
• Easily hackable for node beginners (i.e. not written in CoffeeScript)
• Killer feature will be Dropbox integration where a folder is watched and files are auto-published

I think the on-disk format and general feature set of Octopress is excellent, so a secondary goal will be to try and follow the guidelines of source files & metadata that Octopress supports as much as possible.

If anyone has pointers to code or libraries that might be a good starting point, please leave a comment.

###¹ Markdown editors:

I currently have three different Markdown editors on my iPhone.

• WriteUp (app): This is the app I started with. Great Markdown and Dropbox support. Cool new feature is support for Versions.
• Byword (app): Focused on distraction free writing in Markdown, and that’s it. I’m also using it on my desktop for full screen writing.
• Writing Kit (app): I’ve just added this app, which features the ability to do research with a built in web browser / search. I’ll likely be using this to do research & grab links, and then do the majority of my writing in Byword.

Update September 8, 2013

This blog is now running on the Harp Platform, which is a node.js-based web server with pre-processing built in, and you upload files via Dropbox. Check out the open source HarpJS site if you want to run it on your own. Disclaimer: I am working with the Harp team and couldn’t be happier at using it.