Create a powerful static website with nanoc

Forget Drupal, WordPress and Rails: nanoc compiles your documents into a static website

Web development

We’ve never really loved content management systems and blog platforms, because they force us to use mediocre tools: editing files in a crash-prone web browser, usually with some unusable WYSIWYG editor widget. And to deploy the website, we need to install PHP and MySQL on our web server, which can be hard to trust because of their dubious security track record. Why can’t this be done in a simpler way? Why can’t we just use a quality command- line editor like Vim to edit the webpages? And why does the result need to be a dynamic site if we only add pages to it daily and the rest of the content stays the same anyway?

Luckily, we’re not the only ones who think this way. Five years ago, Denis Defreyne created nanoc, a Ruby-based tool that runs on your own computer and compiles documents into a static website consisting of simple HTML files. You can then write these documents (in formats such as Markdown, Textile or HTML) in your own favourite editor, let nanoc compile them, and upload the result to your web server. As this web server just has to serve a bunch of static files, you don’t have to install PHP, MySQL, Ruby or Rails on it. So not only can you use a very lightweight virtual private server for your website, you have also less chance of being hacked into. Let’s take a look at how this works.


Ruby 1.8.6 or higher

RubyGems 1.3.5 or higher


Step by Step

Step 01


First, install Ruby 1.8.6 or higher and then RubyGems 1.3.5 or higher. RubyGems is Ruby’s package manager, which offers the easiest way to install nanoc: just run ‘sudo gem install nanoc’. After this, install two other useful Gems used by nanoc with ‘sudo gem install kramdown adsf’.

Step 02

Create a website

Run the command ‘nanoc create_site tutorial’ to create a directory named ‘tutorial’ with all the necessary files for a new website. When you go into the directory with ‘cd tutorial’, you see some configuration files like Rules and config.yaml, and directories like ‘content’ and ‘layouts’ with example content.

Step 03

Compile the website

Every time you add or update some content in a nanoc website, you have to compile the website, just as you would do with source code you’re writing for a program. Just run the nanoc command to compile the example content, after which you’ll find the result in the directory output.

Step 04

View the website

Nanoc has an internal web server that you can use to preview your website after you have compiled it. Just run ‘nanoc view’, then you can navigate in your web browser to http://localhost:3000/ to see the resulting index page.

Step 05

Edit your own content

Now that you have seen the basics with the example content, it’s time to update it with your own content. You need to edit the file content/index.html. After you have changed the content, compile the website again and refresh it in your web browser to see the changes.

Web development
Edit your own content

Step 06

Change the title

If you have only changed the HTML content of index.html, your webpage will still have the original title. To change the title, change the line ‘title: Home’ at the top, which defines an attribute title formatted as YAML (YAML Ain’t Markup Language). Recompile and look again at the webpage.

Step 07

Page structure

So how did changing the title attribute result in nanoc updating the HTML title tag? You’ll find the answer to this mystery in the file layouts/default.html. This file defines the template for all HTML files, including the title element which refers to the page’s title attribute with <%= @item[:title] %>.

Step 08

How to change the page structure

When compiling, nanoc replaces the <%= yield %> instruction in the template with the compiled content of each page. You can alter the rest of the template to change the structure of your webpages. For instance, this is the place to add a navigation sidebar and a footer.

Step 09

How to add attributes

You can add arbitrary YAML attributes to a webpage, eg ‘author: “Koen Vervloesem” ’. Then you can make use of this attribute in the template, for instance to automatically show the name of the author both in the HTML head and in the main content of the HTML page.

Warning: file_get_contents( failed to open stream: HTTP request failed! HTTP/1.0 500 Internal Server Error in /var/www/html/ on line 9