Why I've built takitapart using a static site generator, and why DocPad won me over.

As someone who builds complicated and database-intensive web applications, I believed I would the last person to use a static-site generator. I mean, I've developed CMSes, why would I ever go back to something that... crude?

In early 2012, I finally gave in and moved my development projects to GitHub. There, I was introduced to GitHub pages, and the platform they are built on, Jekyll.

It was brilliant.

About the only thing I love more than a elegantly-crafted database schema is text files. Portable, ubiqutous, and future-proof as tech can be. With Jekyll, adding content was as simple as creating a text file.

And like magic, plain HTML comes out the other end. That I can host anywhere. No databases to worry about. No need to worry about upgrading, maintaining PHP, Rails, or whatever. Security, performance, not a problem.

Simple. Clean. Elegant. Sold.

The problem is, I outgrew it. It was a little too simple. It wasn't flexible enough. I had nearly given up on the whole concept, or worse, tried to write my own, when I came across:


Calling DocPad a static site generator isn't exactly fair. Here's how they describe it.

DocPad is a next generation web framework; allowing for content management via the file system, rendering via plugins, and static site generation for deployment anywhere. It's built with Node and Express.js, making it naturally fast and easily extendable. DocPad Intro

I have to admit, that is an incredibly vague description, and I was nearly scared away. Fortunately, all the reviews I read were incredibly positive, and after looking deeper, I realized the vagueness of the description reflected the wide capabilities of the framework.

Here's what sold me:

  • It's built in Node. More and more of my current development projects are built on or around Node, so I wanted a chance to gain as much experience with it as I could.
  • While I can appreciate the pure simplicity of highly-opinionated SSGs, if their assumptions don't match yours, it can quickly become frustrating. DocPad doesn't have any expectations, and frankly doesn't care how you use it. It requires a little more effort to get started, but it pays off. And if you're worried about Blank Page Syndrome, there are some great skeletons available.
  • It has a fantastic rendering pipeline, based on file extensions. Provided you have the right rendering plugin (there are plenty available), you can use any templating engine you'd like, on a document-by-document basis.

    For example:

    • my-post.html.md: A standard conversion from markdown to html.
    • handlebars-rules.html.hb: Maybe you'd rather use Handlebars templates instead?
    • handlebars-suck.html.eco: Nah, I'd rather use Eco templates.
    • compromise.html.hb.eco: Why not both? Yes, this works.
    • the-stylesheet.css.less: Did I mention it can do stylesheets? Renders LessCSS into CSS.
    • scripts.js.coffee: Yup, scripts too.
  • It's modular. They've completely embraced NodeJS's modular philosophy. Need more functionality, chances are there's a npm install ... command that will meet your needs. And if not, it's incredibly easy to extend. I wrote my first plugin before launching my first site.

    That works both ways. If I don't need something, I can take it out.

  • It's dynamic. Or rather, it can be dynamic, if you need it. It's able to generate documents dynamically at runtime. You have the capabilities of a full NodeJS application should you need it. I'm not outgrowing this.

It's best to remember DocPad isn't an application. It's not a CMS and it's not a blog engine. It is a tool that lets you build either of the things, and more, incredibly quickly, and exactly the way you want it.

I'm very new to DocPad - and to Node.js projects in general - and my explorations are just beginning. I can't wait to see what this thing can really do, and I'm excited to share it with you.

March 20 2013.