Get up and running with nanoc on OS X

Dave Everitt 22 Jan 2012, last updated (none)

Nanoc is an easily-learned system for making static websites from templates, text files and other components, because sometimes WordPress, Drupal or Joomla is too much, and you don't want to learn Ruby on Rails or set up databases. The nanoc developer and other users also share the code for their nanoc-powered sites. The nanoc 'getting started' tutorial is excellent, but this is a minimal version for real beginners.

Necessary skills

For nanoc to be of use, you need to be able to:

Install nanoc

You will need Ruby 1.8.6 or greater (you may need Ruby 1.8.7). The nanoc installation guide is brief and effective.

Create a site

Make a folder to contain your website - for instance inside your 'Sites' folder - let's call it 'new-website'.

Open Terminal and go to this folder by typing the command below (or you can type cd, a space, and drag the folder to Terminal window and hit return);

cd Sites/new-website

Then type:

nanoc create_site mysite

…or name the site as you wish (i.e. something other than 'mysite').

You'll see some feedback in Terminal telling you that nanoc has created a site inside a folder called 'mysite'.

Now move into the new site's folder by typing:

cd mysite

(or whatever you named the site)

Compile (create) the site's html files

nanoc compile

A few lines starting 'Loading site data' will appear in the Terminal window.

Start the inbuilt web server:

Open another Terminal window (so you can keep the web server running and continue to compile your site after making changes) and type:

cd Sites/new-website

to move to the folder containing your website, then run the local server so you can view your site before uploading it to a liver server on the web:

nanoc view

You can now see the site in your browser at http://localhost:3000/. You should see nanoc's default content and styles:

nanoc default site appearance

You can leave the server running in the new Terminal window, but if you want to stop it, hit control-C.

Edit your site

The files you'll want to edit are in two folders named content and layouts; another folder output contains the generated pages:

content
this folder contains an index.html file, but this is not a full html page - at the top it has only a heading (using YAML rather than html) and some html content.
layouts
this contains your site's main html template. The content in index.html is inserted into the div id="main" tag in default.html, which contains a template tag containing yeild i.e. put content here.
output
nanoc creates this folder for html pages it generates - you don't need to touch anything in output as it's all created automatically with nanoc compile.

Make changes to the html in these files so that your home page and overall site appears as you want it to. After each change, type:

nanoc compile

and reload the page in your browser to see the changes.

The section at the top of the content page with --- top and bottom is for adding data that files in the layouts folder can use, for instance:

---
title: "My New Home Page"
---

supplies text for the browser's title bar by filling out the HTML title tag in layouts/default.html by using this template tag: (<%= @item[:title] %>).

Add another page

Adding another page means that you will create another file (e.g. 'about.html') in the content folder. To create an 'about' page, type into terminal:

nanoc create_item about

You can also use the shortcut:

nanoc ci about

Open the new file (content/about.html) and add some text, e.g.

<h1>About this website</h1>

<p>This is the about page for my new nanoc site.</p>

Now change the title and add some author data to the top section so that it looks like this (use your real name!):

---
title: "My About Page"
author: "My Name Here"
---

Next, open layouts/default.html and add a conditional template tag so that the author's name only appears on pages if 'author' exists in the top section:

<% if @item[:author] %>
<p>This page was written by <%= @item[:author] %>.</p>
<% end %>

Then nanoc compile again. You'll now be able to visit this page at http://localhost:3000/about/. You'll see your new text, and your name. If you visit http://localhost:3000/ your name won't appear because there's no author data in content/index.html

You've now created a basic website using nanoc. You can add new pages with some basic 'holding' content until you have it all working well looking good, then you'll be ready for the next step, which is…

Using simple markup languages to avoid writing HTML

You don't have to use HTML in your content pages—nanoc can also read Markdown, Textile, and several other markup languages that make it easier to edit web content. The nanoc guide covers this in detail, and although Kramdown (Markdown to HTML) failed with an uninitialized constant REXML error on my OS X Leopard setup with Ruby 1.8.6, a prompt email from Kramdown developer Thomas Leitner provided the solution, now appended to the GitHub issue and fixed in the next Kramdown release.