I don't use DocPad anymore, but this post may still be interesting to those that do. Just keep in mind that the blog you're reading now isn't generated by DocPad and may not match what this post discusses.

Over the past couple weeks, I have been playing with DocPad for another project. As I was learning about DocPad, I started to get the itch to move my blog engine to it (from Octopress). Why? Mostly because trying something new is usually more fun than the status quo :) But also because I prefer NodeJS and JavaScript over Ruby.

DocPad vs. Octopress

Don't get me wrong. Octopress was working perfectly fine for me. It's a great engine. But because it is a ruby application (or perhaps it's built on top of Jekyll, which is a ruby application), I was never going to fully understand its internals well enough to tinker and contribute back to the open source project.

DocPad, on the other hand is a NodeJS application, and so is something I am comfortable enough with to do some tinkering. So, I spent a weekend and a couple late nights toiling away, and you're looking at the results. My blog is now generated by DocPad and I accomplished that without losing any significant functionality in the migration. In the process of getting this revised blog engine up and running, I found several features I needed that were missing, so I have already submitted a handful of pull requests to the DocPad team and to other plugin authors.

To be fair, DocPad probably compares more closely with Jekyll than it does with Octopress. DocPad and Jekyll are both static website generators. Both are kind of swiss army knives and can be used to create any kind of static website, not just blogs. The downside is that if you want to create a blog with either of them, you have to build it out yourself. Octopress, on the other hand, is a collection of scripts and templates for Jekyll that makes it much easier to create a blog without having to really learn Jekyll.

Getting Started Quickly

I looked, and as far as I can tell, there is no one who has really created a comprehensive blog template (or "skeleton", in DocPad terms) that lets you get started as quickly and easily as with Octopress. Fortunately, it wasn't that hard to create one from scratch. I was able to get all of the things I cared about working:

  • Blog posts generated from Markdown files
  • CSS stylesheets generated from Less files
  • Blog post URLs based on the date of the post
  • Disqus support for post comments
  • Tags and tag index pages
  • Good syntax highlighting of code blocks
  • FancyBox support for images in blog posts
  • Arbitrary additional web pages (e.g. my 'Projects' page in the header above)
  • A functional atom feed with relative urls (images, etc) automatically converted to fully qualified URLs
  • A reasonable workflow for draft posts that aren't ready to be published
  • Windows Azure hosting with automatic production-site updates anytime I update GitHub

If you'd like to build off of what I have done, you're absolutely welcome to. The source for this website is available on GitHub:

https://github.com/ervwalter/ewalnet-docpad

Keep in mind that it has all my content in it (which you would need to clean out), and it has my blog's look and feel (which you may not want), but it may be a helpful starting point.

That said, I also plan to create another copy of the code that has my content stripped out and has a more generic look and feel that may be useful as an true skeleton project you can use to get started very quickly.

Building Blocks

For those that are more interested in building there own projects, there are a few non-obvious things I wrote about related to my use of DocPad: