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.
For nanoc to be of use, you need to be able to:
- type into the command line (use Terminal, in Applications/Utilities on OS X)
- install Ruby gems
- understand enough HTML and CSS
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);
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:
(or whatever you named the site)
Compile (create) the site's html files
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:
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:
You can now see the site in your browser at http://localhost:3000/. You should see nanoc's default content and styles:
You can leave the server running in the new Terminal window, but if you want to stop it, hit
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:
- 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.
- 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
yeildi.e. put content here.
- 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
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:
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 %>
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.