Creating a DocPad plugin

In order to complete the switch to DocPad I wanted my blog to support a paged index of my blog posts. I didn’t want to display them all in one big long page, but split them up into groups of 3 or 5 with ‘Older’ and ‘Newer’ links to let users navigate the posts. Sadly this functionality isn’t available by default in DocPad, but never fear DocPad is built with a plugin framework so we can add this functionality ourselves.

In the next couple of posts I’m going to walk through the creation of the Paged Plugin which I recently put together for just this purpose.

Creating the index page

Now that we’ve got Docpad up and running, the last thing thats absolutely essential is to get the site showing the blog posts on the index page. You’d think this would be simple, and it really is, but it stumped me for a little while before I found the appropriate documentation.

Now I’m not certain this is the best way of doing things but it works for me and its simple enough. To display the last N blog posts on your index page do something like this:

1
2
3
4
5
6
7
8
9
10
11
12
<% for document,i in @getCollection('posts').toJSON(): %>

<% break if i > 2 %>

<article id="post" class="post">
<h1><a href='<%=document.url%>'><%= document.title %></a></h1>
<div class="post-date"><%= document.date.toLocaleDateString() %></div>
<div class="post-content">
<%- document.contentRenderedWithoutLayouts %>
</div>
</article>
<% end %>

This simply says loop over the collection of ‘posts’, break the loop if the i variable is greater than 2 (remember this is a for loop so its zero indexed). Then we simply render the article, and use the document.contentRenderedWithoutLayouts rather than the usual @content. We do this since we’re already ‘laid out’ so we don’t need the full layout of the document again.

Blogging with DocPad

In the last post I explained a little about why I’ve moved this site away from Wordpress to a static generator approach using DocPad where I generate this blog from a set of files rather than from a database. This time I’m going to detail a little bit of how DocPad works and the changes I’ve made to get this site running as you see it now.

The Twitter Bootstrap skeleton I’m working with provides a basic set of DocPad plugins to start with. So I’m going to write a little bit about each one and how it fits into the DocPad system. DocPad is pretty smart in that it lets you use lots of different markups and languages. Through its plugin architecture it automatically runs the appropriate scripts based on the file extensions of the files in your project. So for instance if we have a file named hello.html.md it will automatically process any handlers for the .md extension and then expect the result of that to be a .html file. You can even feed one language into another and so on using this extension based mechanism. So a file called hello.html.md.eco will process the file as an Eco file first, then as a Markdown file before outputting it to HTML.

Going Static

After numerous Wordpress disasters, both of my own making and that of nefarious bots and spammers taking over the site, I’ve decided that its time to start over. I’m sure there will be further rants on the topic of the many faults (and virtues) of Wordpress at a later date, but for today I’ve had enough. This time I’m going with an alternative approach using Node.js and DocPad to generate the site statically.