Static Site Generation With Docpad (Part 2)

< Part 1

Setting Up

The simplicity of setting up Docpad was one of the reasons I chose it over Octopress. The Docpad Getting Started Guide is a great intro, so start there. The only difficulty I had was in getting my site deployed to Github Pages, using the Docpad plugin. The Docpad deployment guide makes a lot of assumptions about your level of understanding of how Github Pages works. This is all they provide from the docs:

npm install --save docpad-plugin-ghpages
docpad deploy-ghpages

This installs a plugin that manages pushing your output to Github. However this assumes that you've already created a github repo that the Pages site will be pointing to. It assumes you want to deploy to a gh-pages branch of the repo. This is wrong. To publish a blog to Github Pages, you need to push to your master branch. According to the Github Pages documentation, gh-pages is reserved for project landing pages, not regular site/blog pages.

This is all too confusing. Instead of using the docpad github plugin, I decided to just push the output folder directly to the master branch of my repo using standard git commands. I had to reconfigure Docpad slightly so that the output folder and all the source code were set up separate folders. I recommend setting up your files this way:

    ├── OUTPUT (
    │   ├── icons
    │   ├── img
    │   ├── index.html
    │   ├── posts
    │   ├── scripts
    │   ├── styles
    │   └── vendor
    ├── SOURCE (
    │   ├──
    │   ├── node_modules
    │   ├── package.json
    │   └── src
    │       ├── documents
    │       ├── files
    │       └── layouts

To do this, you just need to tell Docpad where it should save the output. You do that by modifying the file. Per the config docs, you just need to set the outPath

outPath: '../OUTPUT'

This will allow you to create and maintain two separate repositories, one for the output (which gets pushed to Github Pages), and the other for your source code.

Deploying to Github Pages with your own Domain

I decided to host my site on Github, primarily because it's free, but also because it's super convenient to commit and push, then serve everything with the same service.

As briefly explained above, Github Pages works via a specially named repository dedicated for that purpose. If you create a repository named: [username] anything within the master branch of that repository will get hosted out on http://[username] So, for instance, my repository: is hosted out on (which redirects to

The next step is to point your domain to the Github Pages IP address. Currently, this IP address is: but check the docs just to make sure, since it's possible it could change. Next, checkout the Setting up a custom domain with Pages, doc. It tells you to create a CNAME text file with your domain name, in the root of your pages. So for me it was like this:

    ├── OUTPUT (
    │   ├── CNAME <--- contains ""

Once you've committed that to your repo and pushed it up, and you've setup your domain to point to the right IP address, it should take Github about 10 minutes (plus the time for DNS cache to clear which could be an hour or more) to listen for that domain.

And that's it. If you have any questions or need any assistance, leave a comment below or find me on twitter.

Found this useful?

Edit This Page    You too can edit this page! ... just make your change then submit a pull request!

comments powered by Disqus