Blogging platform for hackers - Octopress vs Docpad vs Poole

In this post I will walk through my journey of discovering right blogging platform for my site, share my experiences and findings along the way.

When I decided to blog, I researched on next generation blogging platforms for hackers. Mainstream blogging platforms like wordpress, blogger, tumblr are designed for naive users and aren’t best for developers. Because those platforms doesn’t support features programmers would want like code syntax highlighting, theming using frond end frameworks, Markdown language support, integration with source control repositories, etc.

Static site generators:

I learned that many static site generators are used for blogging platform. The static site generators are basically template engines that takes templated dynamic content and runs it through various processors and converters to generate static html/css/js website. The idea that dynamic content doesn’t need to be always served by a backend server, rather a template engine could pre generate static site from dynamic content is brilliant. Using static site generators provided these benefits and features which I was hunting for

  • Syntax highlighting for code snippets.
  • Customizable layouts and themes using front-end frameworks like Bootstrap
  • Write content using Markdown language.
  • Manage code in source control like github.
  • Easy deployment and hosting on github pages or other hosting providers like Heroku, Amazon AWS.
  • Easy integration with social sharing like Facebook, Twitter and Disqus comments.
  • Mobile friendly response UI.
  • Highly decoupled and No vendor lock in. It’s easy to migrate to a different site generator or switch different hosting provider.

After bit of research narrowed down my choices to Octopress and Docpad and played around with both.

Impressions with Octopress

Octopress (self-proclaimed as A blogging framework for hackers.) is blogging framework on top of Jekyll static site generator. Of course, Jekyll itself could be used, but Octopress makes it easier by providing ruby scripts and themes out of the box. Basically it encompasses Jekyll ,Jekyll plugins, Rake tasks and Themes. The setup process is very easy - just clone the octopress repo, tweak basic configs and start creating posts as Markdown files. I was able to get a blog running in just few minutes, but I wasn’t satisfied with it for couple of reasons

  • I wasn’t pleased with default theme. I had to manually customize the CSS instead of using popular front-end frameworks like Bootstrap, Html5Boilerplate
  • I didn’t like the fact that I need to check in the octopress code itself (scripts, plugins , etc.) along with my posts into source control. This will make upgrading to new version of octopress convoluted.

I didn’t spend too much time with octopress, as I found that it’s not much flexible and some people1 moved from octopress to docpad.

Experiences with Docpad

Docpad is highly customizable and extensible site generation platform built with Node.js. It can be used to build not just blogs, but any kind of Content Management System (CMS). It supports several languages like haml, jade, coffeekup including markdown and has myriad of plugins for everything you need for a blog. It also comes with many prebuilt skeletons for theming.

The plain vanilla docpad doesn’t provide features I needed for blog like generating menus, labeling with tags, listing achieves and requires lot of customization using various plugins. Luckily I found that had all the features I needed, so I cloned his github repo to create my own site. I did not had prior experience in Node.js, so I had to instantly learn lot of modules in node ecosystem like coffee script, eco templates and it presented good opportunity for me to familiarize myself with Node.js. After some struggle I finally managed to get my blog up and running. Then, I used docpad-ghpages plugin to host it on github.

Meanwhile, at my work, We were looking for better way to document our application’s operational and troubleshooting guides. We have been using google sites, but it doesn’t support syntax highlighting or reusing snippets or create any dynamic content. Also using Rich text editor is not convenient as simple markdown syntax. So it wasn’t productive for both authoring and reading. We also wanted better process around reviewing documentation before publishing and tracking of changes. Docpad turned out to be ideal choice. I did a quick proof of concept for a hackday event and it received huge acclamation from colleagues.

Although I liked my blog built docpad, I wasn’t fully satisfied as I felt it was overly complex and it would be hard to maintain for long term.

Migrating Poole using Laynon theme

Short time ago, I came across and immediately liked look and feel of the site. I learnt that it also built using Jekyll, but based on Poole framework. Poole provides basic scaffolding for blog and beautiful themes hyde and laynon. I was able to get it running in just few minutes. I was able to quickly preview articles I created with docpad as I had to simply copy markdown files to _posts directory. I decided to migrate my blog over to Poole laynon theme because of following benefits.

  • Unlike octopress, I don’t have to customize the theme or checkin ruby code into source control. The laynon theme is perfect for me and it had minimal css and layout template files to checkin to source control.
  • It is not so much complex as docpad, so it will be easy to maintain.
  • It provides blogging features out of the box and I don’t have to customize much.
  • Github natively supports Jekyll so I can directly publish Jekyll project to github without having to pre-generate static html files.

Fortunately, had all the custom features I needed like social sharing with facebook, twitter, disqus comments and google analytics tracking. It also shows google analytics data like page views in posts which is pretty cool. So I cloned anandmanisankar’s git repo to create my own blog and migrated over my posts from Docpad. The migration was pretty smooth and did not take very long. While doing this I kept basic skeleton in a separate branch so that others can easily clone and use it for their site. In my next post I will provide instructions on how to setup your own site based on my project as foundation.


Octopress would be best option if you want to get started quickly and use it as is without much of customization. Docpad is very flexible and extensible to create any kind of site. But it is more complex and has steep learning curve if you are not familiar with Node.js. Poole provides right mix of essential blogging features, beautiful themes and flexibility for customization. I feel it is the best platform for my needs.

1. References on people migrating from Octopress to Docpad

comments powered by Disqus

Facebook Comments