Official website for Linux User & Developer

Create a powerful static website with nanoc

by Koen Vervloesem

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

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.

Pages: 1 2
  • Tell a Friend
  • Follow our Twitter to find out about all the latest Linux news, reviews, previews, interviews, features and a whole more.
    • Robin L

      How do you implement an efficient search function?

    • Pascal Bleser

      Hey Koen :)

      Incidentally, and as you probably know, we’re migration from Drupal to nanoc (going to go live really soon now ;)). And indeed, nanoc absolutely rocks. We’re doing really complex stuff (such as exporting schedule information from Pentabarf) and using nanoc as a framework has been a lifesaver.

      Robin: nanoc has no facilities for search and search cannot be implemented in a “static way”. For fosdem, we are using Apache Solr and feeding its index directly from nanoc (with a custom nanoc command). We also implemented a tiny webapp with Sinatra that performs the search queries against Solr and displays the results (and handles the faceted search parameters, paging, etc…).

    • Pingback: Create a static website with nanoc « 0ddn1x: tricks with *nix()

    • Pingback: Links 14/11/2012: Linux Mint 14 RC, India’s Educational Android Tablet | Techrights()

    • I used nanoc for a couple of years. It solved a bunch of problems like dealing with headers and footers, having different layouts for different pages etc. It allowed me to do version control on the files which then meant easy rollback if I made mistakes. It also helped out when I did major overhauls.

      So ultimately I left nanoc and went to WordPress. There were several reasons:
      1. I code all day and try to run a martial arts school at night. I just got tired of having to grind my own coffee, so to speak.
      2. WP and similar frameworks have tons of free plugins that meet my needs, without me having to write the code to do it. One example is creating a mobile site, super easy under WP, more work under nanoc.

      I would recommend nanoc, but for me it just came down to time management.

    • It seems like you actually fully understand a great deal about this
      particular topic and it shows thru this amazing posting,
      called Window Treatments “Create a powerful static website
      with nanoc | Linux User”. Many thanks ,Rafael