As I've mentioned previously on my blog, I've jumped ship from using Wordpress.com to a DocPad produced static site that is hosted on GitHub using their "pages" feature. In this post I'll walk through the basic steps I took to get up and running with DocPad.

Installing DocPad

You'll need to have Node.js and NPM installed before you go any further. Once you've sorted that out, we'll continue.

First, you'll need to open up a command prompt and type the following command.

npm install -g docpad

Note: If you run into any permission problems you may need to slap a "sudo " infront of it.

This installs docpad as a global command that'll now be available where ever you type it. From here you'll need to create a directory to house your docpad development area and then get docpad up and running.

mkdir geekonomics
cd geekonomics
docpad run

In the dark dark folder, some skeletons lived

At this point, docpad will provide you a list of skeletons you can base your site upon. These include the HTML5 Boilerplate, Twitter Bootstrap, various flavours of them and a few others as well. For the sake of finding our way around docpad, let's make like a jellyfish and go with "No Skeleton".

Docpad will now go about grabbing all the Node.js modules your new site will use and create the basic folders. When it has finished, it'll load up a load web server and tell you the address (usually http://localhost:9778). Don't expect to find much there, yet...

Not Found

We picked the "No Skeleton" option, so docpad has given us a blank canvas to work with. If you go to the site as it stands, you'll just get a "Not Found" message.

Bits n' Bobs

Taking a look at the folder we've run docpad within, you'll see that it's created a few folders and files. These are pretty important going forward so I'll briefly explain each of them.

• node_modules: If you haven't used Node.js before, this is simply where all the installed modules for this site are kept. Nothing to really concern yourself with at the moment.
• src: This is where all the action will be happening.
  • documents: From what I understand, any file within this folder (or subfolders thereof) will be specially processed. We'll get into that soon enough.
  • files: Simply put, all docpad is going to do with these files is copy them to the output folder.
  • layouts: Collection of files that'll provide layout for files within "documents"
• out: You probably won't see this yet, but it'll be created when you start creating your site. It holds the output of docpad, the finished site.
• docpad.coffee: The sites docpad settings. It's written in CoffeeScript which is designed to make JavaScript a little more presentable and nicer to write. You could always convert between CoffeeScript and JavaScript if you want to avoid using it. Docpad will accept JavaScript, JSON, CoffeeScript and CSON based configuration files.
• package.json: This file contains information used by NPM to track the modules that the docpad site needs, information about your code and any other modules you want to use.
• README.md: A standard readme file based in markdown, for you to use.

Baby steps

Let's get started. Fire up an editor of your choice, create a file src/documents/index.html and get creative with some HTML content within it. Once you've saved the file, checkout your command prompt that should still have docpad running. You'll see some activity where it spotted the file you created and regenerated the site. Confirm this by refreshing your browser http://localhost:9778.

Template engine plugins

Before we go any further, I'd like to mention template engines. Docpad supports a diverse range of template engines via plugins, which are easy to install and use. For this post I'll initially be using one that adds support for embedded CoffeeScript. You'll first need to stop docpad (Ctrl+C) and then run the following command to install the plugin.

docpad install eco

Now rename src/documents/index.html to index.html.eco and edit the contents to include something like:

<p>It's all fun and games.</p>
<p>Generated on: <%= new Date().toString() %></p>

Fire docpad back up with docpad run and go to your browser and refresh. You should now see our same old index.html page with a date outputted. Docpad saw that your file ended with .eco and processed it with the embedded CoffeeScript plugin. It then chopped the .eco off the name when it created the final index.html file within the out directory. Clever ;-)

You could of course leave the file as index.html if you've no need of any dynamic content during generation. I only did this as an excuse to desribe the template engine before we moved onto...

Document metadata and layouts

Remember how I mentioned that src/documents was a special place. Well every (text based) file that lives in that folder can have metadata associated with it. We do this at the top of the file (like our src/documents/index.html.eco) between two lines of --- and writing some YAML or you could use CSON if you indicate it with --- cson at the top.

---
title: "Welcome to the jungle!"
layout: "default"
---
<p>It's all fun and games.</p>
<p>Generated on: <%= new Date().toString() %>

Now when docpad generates the page, it'll internally carry the data you've specified... and throw an error. Why!? Because we've used a special metadata item of layout and set it to "default". This tells docpad that we want to wrap the output of this file within a layout file. We'd better go and create one then as src/layouts/default.html.eco. Make sure you add that .eco to the file name and throw in the follow as the contents:

<html>
<head>
  <title><%= @document.title %> | My Website</title>
</head>
<body>
  <h1><%= @document.title %></h1>
  <%- @content %>
</body>
</html>

We're getting somewhere now! Refresh and you'll see that your content has been injected into the layout file we've created. Now we could have numerous pages that use this layout, which should save us a lot of time. If you've other layouts you'd like to use, simple create them within the layouts folder and specify them in the metadata of the document. It's even possible to have nested layouts.

src/documents/pages/about.html

---
title: "About me"
layout: "page"
---
<h2>About me</h2>
<p>Some interesting facts about myself...</p>

src/layouts/page.html.eco

---
layout: "default"
---
<p>Page: <%= document.title %></p>
<div class="content">
  <%- @content %>
</div>

In the above example, the about page would be injected into the page layout before it's then injected into the default layout. You could use this to provide a similar layout for a set area of your site (e.g. pages, posts, projects...) compared to other areas of your site.

Getting out of dodge (wordpress)

There are a few methods available to get your posts out of wordpress. However, I decided to make my life harder and do it manually. I won't go into the process I put myself through in detail but it involved the following steps:

• Log into Wordpress.com dashboard for the blog
• Use the "Export" feature to download all posts and pages.
• Save the XML file provided.
• Created script to interate over the XML file, containing the blog posts.
• Used pandoc to convert posts to markdown.
• Spent a while fixing issues with HTML encoding, wordpress shortcodes, code samples and more.

In the end I had a folder full of markdown files named after their ID: /posts/*.html.markdown