Expanding the Power of nanoc with Rake

Overview

nanoc in itself is great for generating templatised static HTML pages. It's very powerful and flexible with good built-in filter support and easy user extensibility.

However, what it doesn't really venture into is handling the peripheral tasks associated with a site. To be fair, this isn't really its job; think of nanoc as being like a compiler you can write extensions for. You still need to be able to package up and deploy your site and you probably have some other assets that nanoc cannot manage. Enter Rake.

Here are some of the extensions I've added to my site via Rake that provide some useful features or automate mundane tasks.

All of these small Rake tasks live within the tasks subdirectory inside nanoc.

nanoc

This file provides some basic tasks for helping automate nanoc

1. Download nanoc.rake.

This then gives you:

• compile just wraps nanoc co
• clean nukes everything under output - for assets held under here, I've instead moved these out into a separate top-level assets directory and copy in from there.
• auto invokes the nanoc autocompiler with a default port (9210).

These tasks aren't fantastically useful in their own right and mainly wrap nanoc itself; however it does mean you can stay within using Rake at all times.

Sitecopy

Sitecopy is a fantastic straightforward automated/batch FTP tool specifically designed for maintaining static Websites. If you only have FTP access to your Web space, it's a perfect partner for nanoc.

1. Download sitecopy.rake.

Install sitecopy either via your favourite package manager (Ubuntu has it via Synaptic) or from source.

Sitecopy needs a working area directory and an rc file. For details of how to setup the rc file, see NoBlueScreens guide to setting up sitecopy which runs through everything.

This Rake task assumes the following:

• You have a top-level directory in your nanoc site called sitecopy. This is used as the working directory for sitecopy. Note: this must only have permissions u+rwX (specifically not readable to all).
• Your sitecopy rc files lives in sitecopy/sitecopyrc - again permissions are important here as this file can only be readable by the current user (i.e. u+r not a+r).

You then have two tasks available:

• init runs the one-off sitecopy initialisation. You'll need to do this once before you attempt to upload.
• upload runs a sitecopy update to update the remote server with the contents of the output subdirectory.

It's definitely worthwhile reading the sitecopy man page before starting to play with this as sitecopy is quite a powerful and flexible tool.

Static Assets

Sometimes you just need a straight copy of files from assets to output. This small Rake task does just that for the assets/files subdirectory, which contains my source code snippets.

1. Download static.rake.

This has one task:

• static just copies everything from assets/files and assets/css into output - trivial. If you had images also you could easily extend this to copy those too; I don't though.

Validation

I use the WDG HTML Offline Validator, mainly because it is easy to setup and is fairly friendly in reporting errors. A nice advantage of this is that it gives you offline validation, without needing to post pages over to the W3C HTML Validator. This means it's fast and can be used when you don't have a internet connection. The W3C Validator can be setup to run in offline mode too but I found the WDG validator to be trivial to get working.

1. Download validate.rake.

Install the WDG Validator script. For Ubuntu, this is available in Synaptic. Otherwise, follow the instructions from their site to install.

This gives only a single Rake task:

• validate trawls your output directory and runs each .html file through the validator, reporting any errors.

Link Checking

The W3C Link Checker is also available as a script to download and use via the command line. This makes it perfect for automating link checking a nanoc site, but there are some caveats. You obviously need to be online to use it. As it can fetch a large number of links, it is quite slow too, taking several seconds per local page, even for a small number of links. This quickly adds up if you have a large number of pages (100+) but you do gain the knowledge that your links are good. Because of this, I usually run this manually and not as part of a normal site build - that is, a final stage before an upload onto the live server.

1. Download checklink.rake.

Install the W3C Link Checker script checklink. Again, this is available directly from Synaptic for Ubuntu fans.

You then have a single Rake task available:

• checklink which trawls your output directory and checks all links on each .html page it finds.

Sass

This task adds support for processing Sass stylesheets. No more mucky handcoded CSS files.

1. Download sass.rake

A single task is available:

• sass plucks all .sass files from within the assets/sass subdirectory from the top level of your nanoc project, processes them via sass and dumps the resulting CSS to output/css.

Putting It All Together

Now we have all these tasks, all that's left is to wire them together into the top-level Rakefile.

1. Download Rakefile.

This is the standard nanoc Rakefile but with the default task changed.

 rake -T

 rake auto       # Start the nanoc autocompiler.
 rake checklink  # Check links via W3C Link Validator (slow).
 rake clean      # Remove any temporary products.
 rake clobber    # Remove any generated file.
 rake compile    # Compile site HTML using nanoc.
 rake default    # static, sass, compile, validate.
 rake init       # Initialise sitecopy.
 rake sass       # Generate CSS files from Sass templates.
 rake static     # Copy static assets into output.
 rake upload     # Upload to Web via sitecopy.
 rake validate   # Validate HTML/XHTML output via WDG Validator