Why I like Nanoc

I have been using Nanoc by Denis Defreyne more and more recently. It has
that rare combination of simplicity and flexibility, and it is now my framework
of choice for developing new, simple websites.

Nanoc is a static site generator

Like all static site generators, Nanoc takes a bunch of source files and
transforms them into HTML pages. It nicely separates content from layout,
allows for uncluttered source files using text filters, and provides hooks and
scripts for common deployment tasks.

My typical workflow with Nanoc

My process of building websites using Nanoc typically looks like this:

What I like about this workflow is that lots of moving parts are neatly in
place. When there are only really two tasks to perform (generate the site and
deploy to the server) on which everything else is hooked, the process of site
maintenance is greatly simplified. There is nothing to remember, it is all
basically self-documenting (after you have gotten to know Nanoc, of course).

What’s more, the Ruby ecosystem Nanoc springs from is very vibrant and full of
useful tools, making it much easier to stand on the shoulders of
giants.1 And with the advent of Bundler, the last real hurdle of
managing Ruby Gem dependencies has been overcome. I can now recreate and deploy
my site in a couple of easy steps:

git clone repo.git
bundle install
nanoc co
rake deploy

That is:

Clone Git repository;

Let Bundler set up all required dependencies;

Let Nanoc generate a fresh copy of my site;

Let Rake push it to the live server.

These are simple steps that even teammates unfamiliar with the world of the
terminal and Ruby can learn and use.

Shortcomings

Nanoc is not without its faults, and pinpointing them is, I think, both fun and
a crucial step in improving the system.

The central Rules file handles routing, layouts and filters. It can easily
get cluttered, as you have to specify rules for all these seperately.

Because Nanoc supports different data stores, working with a filesystem store
is not as efficient as it could be.

Nanoc’s gem dependencies are unclear, requiring some trial and error and
numerous gem install’s to get all parts working.

Item identifiers can be confusing, as they seem to – but don’t – map to
file paths. This makes it difficult to have multiple items by the same name
(like sitemap.xml and sitemap.html). Also, a file like .htaccess has no
valid identifier, requiring you to route a htaccess.txt file to a
.htaccess file. It works, but to someone unfamiliar with the system, it is
not immediately clear how.

It can be confusing to sometimes use Rake and sometimes use Nanoc. Nanoc
provides a few Rake tasks, and it is not obvious why the task ‘generate a new
item’ would be handled by nanoc while ‘check for invalid links’ would be
handled by rake.

Nanoc can be slow sometimes, depending on your content and applied filters.
There is an autocompiler that only compiles changed files as needed, but it
is not perfect yet. It is especially cumbersome when an exception occurs and
it quits.

content dependency resolution works pretty well, but sometimes files change,
influencing other files but not triggering re-generation of those files. This
applies to helpers and binary items mostly.

Nanoc hasn’t got a real good system in place for binary static cotent.
Hacking your own solution for images, PDF’s and other stuff is not that bad,
but as everything else is so neatly in it’s own place, it would be great to
see some kind of convention evolving for this.

It can be cumbersome to generate files and filters manually. A generator
system could cut down development time even more.

The fun thing with open source projects like Nanoc is that I can dive into the
source code myself and adapt the system to my needs. And that is exactly what I
intend to do with some of these issues I have.

Overall, I think Nanoc is a very well built and mature project, that is a joy
to work with.

I used to develop static websites with a home-grown PHP-system. Although the PHP world shares a lot of code, it has neither the culture of neat libraries nor a system to easily distribute it, like Ruby has with gems. ↩

nanoc

development

ruby

Arjan van der Gaag

A thirtysomething software developer, historian and all-round geek. This is his blog about Ruby, Rails, Javascript, Git, CSS, software and the web. Back to all talks and articles?

Discuss

You cannot leave comments on my site, but you can always tweet questions or comments at me: @avdgaag.