Creating Simple Site with Nanoc

In the previous part of the series we discussed what the static web site generation is and why you should use it. In the next few articles we’ll go through the creation of the site and we’ll add few blogging features. As a framework we’ll use nanoc and in this article I’ll walk you through some basics.

Things you need to install are ruby, ruby gems and nanoc. Ruby is the language and environment. Ruby gems are the package management system for ruby. Nanoc is the platform for static site generation. Based on the technologies used on your site you probably have to download more gems but for the first example this should be enough.

On the nanoc homepage there is a great guide how to install all of the three important components. Follow the instructions and when you are ready we start with the hello world site.

First Steps

Let’s make sure that you’ve downloaded all three components and they are properly configured. Run following commands.

% ruby -v
ruby 1.9.3p327 (2012-11-10) [i386-mingw32]

% gem -v

% nanoc -v
nanoc 3.5.0 (c) 2007-2013 Denis Defreyne.
Running ruby 1.9.3 (2012-11-10) on i386-mingw32 with RubyGems 1.8.24.

Now let’s create the web site and switch to the working directory.

% nanoc create-site hello-world
% cd hello-world

You can use quotes for multiple words in the site name just like this nanoc create-site "My Web Site with Spaces".

When you are in the root directory of our web site, compile the project running the nanoc command. It is the same as running nanoc compile.

Then start local web server by running nanoc view. It is better to start local web server in different process than your command prompt by running start nanoc view with Windows Powershell.

With nanoc help <command> you can check the documentation for command’s parameters and switches.

For example you can use nanoc view -p 3001 for running web server on a different port. This is very useful if you are working on multiple nanoc sites at once.

Let’s compile and run the web server.

% nanoc
% nanoc view

Open your browser and check the output on http://localhost:3000.

First compiled application but it has issues with encoding.

Everything is working and your application is ready to use. Or is it? Did you notice there is something wrong with the encoding? Let’s take a look and fix this issue.

Fixing Broken Encoding

The lib folder located in the root project directory contains ruby scripts and user defined methods. This is the place where you can put your code, create custom helpers and modules and set up the application environment.

Go to the folder and edit default.rb. Set the default internal encoding to UTF-8 with this line.

# All files in the 'lib' directory will be loaded
# before nanoc starts compiling.
Encoding.default_internal = Encoding::UTF_8

Compile the site with the already well known nanoc command and the result should look like this.

Hello world application with fixed encoding.

The encoding is fixed and everything is working now. We created our first nanoc hello world application. Well done!

Hello World

To modify the content of the main page just go to /content/index.html and insert custom html. The first few lines between - - - delimiters are the item’s metadata. For now it just contains title of the page but in the future it can hold many information for custom purposes.

Modify the file to following.

title: Hello World!

<h1>First Site Created with nanoc</h1>

<p>Hello World from nanoc!</p>

Compile the site and review it in the browser on the http://localhost:3000. You should see your new custom content. You cant play with the site.

Hello world from nanoc


In this article we created our first web site using static site generation. The power of nanoc hasn’t been revealed yet. But you’ll see it soon enough.

More difficult sites with the generic content will benefit from the nanoc capabilities much better than simple hello world application and I hope you’ll fall in love with this framework as I did.

Would you like to get the most interesting content about programming every Monday?
Sign up to Programming Digest and stay up to date!