Take back your site, with nanoc!

How I turned H3RALD.com into a 100% static, hassle-free web site

Why I don't need a blog platform ⇈

There's nothing inherently wrong with blog platforms like Wordpress: they allow anyone to publish content on the web using a user-friendly administration area. They were built with one thing in mind: make publishing content on the web something as simple as possible, even for people who don't know anything about HTML, let alone server-side scripting.

What about people who do know about web development though? Do they still need a blog platform? Depends. If you are comfortable with editing files using a text editor, if you enjoy using the command-line on a daily basis, if you like programming and hacking a little bit, if you don't really care about fancy and user-friendly administration backends… then you probably don't.

All you need is a system to transform a bunch of source files into a web site. The good news is that such system exists – and you're also spoiled for choices!

Introducing site compilers ⇈

The first site compiler I discovered was Webby:

[…] Webby works by combining the contents of a page with a layout to produce HTML. The layout contains everything common to all the pages — HTML headers, navigation menu, footer, etc. — and the page contains just the information for that page. You can use your favorite markup language to write your pages; Webby supports quite a few.

There are quite a few applications like Webby, such as:

There are probably even more, with different features, but they all try to solve the same problem: provide a way to generate static web sites in an automated way.

I spent some time reading about each one of them, evaluating the pros and cons and in the end I decided to go for nanoc, simply because it was the only one that seemed to fit all my needs.

A quick overview of nanoc ⇈

nanoc is a nifty tool written in Ruby suitable for […] building small to medium-sized websites. In other words, anything which doesn't involve some fancy user interaction. For what concerns blogs, the only user interaction is comments – but that's fine, because there's more than one web service for that, such as Disqus or IntenseDebate.

Some details on the project

Compared to the alternatives, nanoc is one of the most mature and most maintained, having hit just a few weeks ago its 3.0 release. Its creator, Denis Defreyne, uses it for his own web site and is involved with the project on a daily basis, both coding and offering support to nanoc users like myself who regularly ask questions on the nanoc user group.

Denis also seems very concerned about keeping documentation up-to-date – something that really impressed me from a technical writer's point of view. The tutorial he put together will get you started in no time, and the manual will explain everything else you may possibly want to know. When release 3.0 came out he even put together a migration guide. If this is still not enough and you don't mind spending some time extending the system, nanoc's RDoc documentation is very comprehensive compared to other Ruby projects.

Sites, Items and data sources

nanoc ships with a really neat command line tool that can do most of the work for you. Nanoc3 create_site h3rald will create a new web site in a folder called h3rald. The contents of this folder are laid out according to a particular logic (convention over configuration, remember?) So:

  • content – your articles, pages, stylesheets, images, …all the site content and assets.
  • layouts – the site layouts (and partial layouts)
  • lib – place your custom ruby code and vendor libraries here
  • output – your “compiled” site, ready to be deployed
  • config.yaml – your site's configuration file. The only one (and it's just a few lines)
  • Rakefile – place any custom Rake task here
  • Rules – defines the rules for compilation, layout and routing

Here's the default config.yaml file:

--- 
data_sources: 
- items_root: /
  layouts_root: /
  type: filesystem_compact
  output_dir: output

A data source in nanoc defines where data is retrieved from to create the web site. By default, the filesystem_compact data source requires that you create two files in the /content folder for each article or page of your web page:

  • One containing the actual content of the page
  • Another for the page's arbitrary metadata

By personal preference, I chose the filesystem_combined data source, which allows you to combine the content and the metadata of a page in a single file.

The source code for this very article, for example, starts like this:

-----
type: article
tags:
- website
- ruby
- programming
- writing
date: 2009-09-15 13:32:51.049000 +02:00
permalink: take-back-your-site-with-nanoc
title: "Take back your site, with nanoc!"
toc: true
-----
Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly 
knew HTML and CSS, nevermind server-side languages, so I remember creating a _pseudo-template_ for
 the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. 
This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change
 in all the pages of the site – the whole eight of them.

At run time, the content goes through a Textile filter and the metadata is used in layouts, to generate tag links automatically, for example.

Layouts, filters, and helpers

Layouts in nanoc are similar to layouts and views in Rails, but much simpler. The same applies to helpers. Here's a snippet from my default layout:

<div id="container">
          <!-- CONTENT START -->
          <div id="content" class="clearfix<%= (@item[:permalink] == 'home') ? ' home' : ' standard' %>">
            <h2><%= @item[:title] %></h2>
            <%   case @item[:type]
                when 'article' then%>
                <div id="content-header">
                  <%= render 'article_meta', :article => @item %>
                </div>
              <% end %>
              <hr />
              <div id="content-body">
                <%= yield %>
              </div>
              <div id="content-footer">
                <div class="share">
                  <script type="text/javascript" src="http://w.sharethis.com/button/sharethis.js#publisher=6e34d60c-b14e-4c19-9b2f-7c35a9f0ab09&type=website&linkfg=%23a4282d"></script>
                  <% if @item[:feed] then %>
                  <a href="<% @item[:feed_url] || @item[:feed]+"rss/" %>" type="application/rss+xml" rel="alternate"><img src="/images/theme/feed-icon-14x14.png" alt="#"/>H3RALD - <%= @item[:feed_title]%></a>
                  <% end %>
                </div>
                <%= render 'article_buttons' if @item[:type] == 'article' %>
              </div>
            </div>

This source code snippet shows quite a few features of nanoc's layouts:

  • You can access the metadata of the page which is being rendered using the @item, so @item[:title] returns the page's title, for example.
  • Layouts can be nested, and behave like Rails's partials. The render takes a string parameter (the name of the layout to render) and an optional hash parameter to pass variables to the layout.
  • The yield method is used to include the content of a page.
  • Layouts support any kind of filter, like ERB for example. Go crazy.

Helpers can be used in layouts to perform common tasks, like creating links, feeds, navigation elements and so on. Check the source code docs for more info, and of course feel free to create your own as you see fit.

Finally, filters are used to filter content markup. nanoc ships with almost everything you need, from Textile to Haml to RDoc, but nobody forbids you to create your own, and it's dead easy.

Rules and tasks

While tasks (as in Rake tasks) do not constitute a huge part of nanoc (but as usual, you may need to create your own to perform custom operations), Rules became, as of version 3, one of the key concepts to grasp in order to make everything work. Rules are stored in the Rules file of your nanoc site, they can be used to:

  • Define routes, i.e. where pages are deployed in the output folder.
  • Define how pages are compiled, which filters to apply to a particular set of pages, which layouts to use, etc.
  • Define how layout are handled, which filters to apply to a particular layout, etc.

You can find more information in the manual, along with other important information, but for now, let's say you should be familiar with most of nanoc's jargon and how it works. Let's see what you can do with it, in practice.

Migrating from your blog platform ⇈

As of version 7, h3rald.com has been powered by the Typo blog platform. If you are not familiar with it, let's just say it's a sort of Wordpress built on top of Rails: database backend, pretty admin front-end, tags, comments, and all sort of things a blog may need. While Typo is pleasant enough to use, it has all the inherent disadvantages of any other similar platform:

  • It relies on a database
  • It relies on server-side scripting to render pages
  • It uses a complex caching mechanism to produce, ultimately, semi-static pages
  • It may be subject to exploits, attacks, high server loads, and similar
  • You can't really customize it beyond a certain point
  • You have to upgrade your backend frequently, and often is not as painless as you may expect
  • You can't use versioning tools like git for your content, as it's stored in a database

I'm not claiming that nanoc is blogging's silver bullet (it was not created for that), but for sure:

  • It does not rely on a database
  • It does not rely on server-side scripting to render pages (not in real-time, anyway)
  • It does not need a complex caching mechanism simply because it produces static pages
  • It is definitely less prone to nasty things
  • It's extremely flexible and hackable with very little effort
  • You don't have to upgrade all the time, but it is really painless if you decide to
  • You can use git and similar: your content is in plain old text files

Rants are beside the point, suffice to say I recently convinced myself that switching from Typo to nanoc was a good thing, so let's see how it worked out.

Posts, pages and comments

Out of Typo's MySQL database, I just wanted to get the following data:

  • Pages and posts
  • Tags
  • Comments

Following the approach used by Jekyll, I decided to use the simple and powerful Sequel gem. I'm sorry to disappoint you, but the whole migration process can be summarize with the following Rake task:

task :migrate, :db, :usr, :pwd, :host do |t, args|
    raise RuntimeError, "Please provide :db, :usr, :pass" unless args[:db] && args[:usr] && args[:pwd]
    db = Sequel.mysql args[:db], :user => args[:usr], :password => args[:pwd], :host => args[:host] || 'localhost'
    # Remove all existing pages!
    dir = Pathname.new(Dir.pwd/'content')
    dir.rmtree if dir.exist?
    dir.mkpath
    # Prepare page data
    dataset = db[:contents].where("state = 'published' || type = 'Page'")
    total = dataset.count 
    c = 1
    total_tags = []
    dataset.each do |a|
      puts "Migrating [#{c}/#{total}]: '#{a[:title]}'..."
      meta = {}
      meta['tags'] = get_tags a[:keywords]
      meta['comments'] = get_comments db, a[:id]
      meta['permalink'] = a[:permalink] || a[:name]
      meta['title'] = a[:title]
      meta['type'] = a[:type].downcase
      meta['date'] = a[:published_at]
      meta['toc'] = true
      meta['filters_pre'], extension = get_filter db, a[:text_filter_id]
      contents = convert_code_blocks meta, a[:body]+a[:extended].to_s
      write_page meta, contents, extension
      c = c+1
    end
  end

That's it. Well, almost: you can find the get_comments, get_tags and get_filter methods in a separate utility file. Nothing special really, just a few convenience methods wrapping queries or simply processing data. Note how all information, including tags and legacy comments, is saved in each page's metadata. The write_page method simply creates a file in the /contents folder.

Filters and highlighters

On my old site, I used mainly Textile and Markdown to write posts. However, some of my really old articles used BBCode, whose corresponding filter is not available in nanoc. No worries, I soon found out that creating a new nanoc filter came down to this:

require 'rubygems'
require 'bb-ruby'

class BbcodeFilter < Nanoc3::Filter
  identifier :bbcode

  def run(content, args)
    content.bbcode_to_html
  end

end

Yes, that's it. Granted, the bb-ruby gem does all the work, but notice how easy it is to just plug in new Ruby code into nanoc's architecture!

The next big challange was code highlighting. After a quick research, I found at least a half dozen of possible solutions to highlight source code. Some were javascript based, others were based on a server-side language like PHP, Ruby or Python. Again, I looked at Jekyll for inspiration and discovered they integrated the Pygments Python library. Why use a Python library for code highlighting in a Ruby-based project? Because there's nothing to stop you (if you can run Python on your server, that is), because it looks very neat and because it supports a lot of different programming languages.

Lazy as I am, I more or less dropped Chris Wanstrath's Ruby wrapper into my /lib folder (I just used Open3 instead of Open4 for Windows compatibility), and monkey-patched nanoc's filtering helper as follows:

module Nanoc3::Helpers::Filtering

  def highlight(syntax, &block)
    # Seamlessly ripped off from the filter method...
    # Capture block
    data = capture(&block)
    # Reconvert 
    data.gsub! /<%/, ''
    # Filter captured data
    filtered_data = "\n<notextile>"+Albino.colorize(data, syntax)+"</notextile>\n" rescue data 
    # Append filtered data to buffer
    buffer = eval('_erbout', block.binding)
    buffer << filtered_data
  end

end

include Nanoc3::Helpers::Filtering

There you go, another thing sorted.

Tags and Feeds

Adding tagging support was a tiny bit more tricky. nanoc supports content tagging out-of-the-box though metadata and a simple helper, but I wanted to create tag pages (with feeds). Nothing too difficult though, it all came down to a simple Rake task:

task :tags do
    site = Nanoc3::Site.new('.')
    site.load_data
    dir = Pathname(Dir.pwd)/'content/tags'
    dir.rmtree if dir.exist?
    dir.mkpath
    tags = {}
    # Collect tag and page data
    site.items.each do |p|
      next unless p.attributes[:tags]
      p.attributes[:tags].each do |t|
        if tags[t]
          tags[t] = tags[t]+1
        else
          tags[t] = 1 
        end
      end
    end
    # Write pages
    tags.each_pair do |k, v|
      write_tag_page dir, k, v
      write_tag_feed_page dir, k, 'RSS'
      write_tag_feed_page dir, k, 'Atom'
    end
  end

Again, you can find all the other simple utility methods in my utility file.

When it came to feeds, I decided to create a new method for the Blogging helper to create RSS feeds, although nanoc does come with an Atom feed generator:

def rss_feed(params={})
    require 'builder'
    require 'time'
    prepare_feed params
    # Create builder
    buffer = ''
    xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
    # Build feed
    xml.instruct!
    xml.rss(:version => '2.0') do
      xml.channel do
        xml.title @item[:title]
        xml.language 'en-us'
        xml.lastBuildDate @item[:last][:date].rfc822
        xml.ttl '40'
        xml.link @site.config[:base_url]
        xml.description
        @item[:articles].each do |a|
          xml.item do
            xml.title a[:title]
            xml.description @item[:content_proc].call(a)
            xml.pubDate a[:date].rfc822
            xml.guid url_for(a)
            xml.link url_for(a)
            xml.author @site.config[:author_email]
            xml.comments url_for(a)+'#comments'
            a[:tags].each do |t|
              xml.category t
            end
          end
        end
      end
      buffer
    end
  end

Nothing too daunting, once you get used to Ruby's XML builder. I followed a similar approach for my monthly archives

3rd-party services

Finally, the interactive bits. I basically turned to third-party services and a bit of jQuery for everything which required user-interaction or pulling data from other web sites. Here's a list of services and APIs I currently use:

If you want to know how I integrated them, check out my /js folder, it was very simple, really.

Conclusion ⇈

I was very happy of switching to nanoc. It didn't take me long, and I spent most of the time with non-nanoc issues (brushing up jQuery, CSS, graphics, etc.). Of course knowing the Ruby programming language helps, and if you're not comfortable with hacking your way a little bit, then maybe it's not for you.

Personally, I've been waiting for something like nanoc for a long time: its simple and yet powerful architecture makes you able to do virtually anything with it. For the first time in a long time, I feel like I'm in complete control of my web site, I know every bits of it and if I want to change the way it works or looks I only have to touch a few files.

nanoc's metadata is mindblowing for its simplicity and power: although you're not dealing with a database, you can query your content in the easiest ways possible. Whenever I needed a way to easily access pages, filter them, add extra logic to them, I just added metadata. If you forget something, you don't have to change your database tables, create new relationships or anything of the sort, you simply add metadata to pages.

Be warned that tweaking nanoc gets addictive very quickly: you soon end up creating silly little tasks for making things just the way you want. For me, adding a new article to my blog now just means this:

$ rake site:article name=take-back-your-site-with-nanoc
$ vim content/articles/take-back-your-site-with-nanoc
... write & close the file ...
$ Nanoc3 compile

…Exactly what I need. Nothing more, nothing less.