Getting Started

Requirements

This tutorial does not cover the installation of nanoc. For information on how to install nanoc, as well as Ruby and Rubygems, check out the Installation page.

This tutorial requires kramdown. Kramdown is a Ruby implementation of Markdown, which allows you to write HTML in a easy-to-use plain text format. If you haven’t used Markdown before, don’t fear—it’s quite easy to use. To install kramdown, jump to your terminal and type:

% gem install kramdown

You should also install adsf, a tool that allows you to fire up a web server in any directory, which is very useful for previewing compiled nanoc sites. nanoc’s view command, used in this tutorial, requires adsf to be installed. Install adsf like this:

% gem install adsf

Be sure to install adsf, not asdf. No, that’s not a tyop!

nanoc also requires a basic level of experience with Ruby. It is possible to use nanoc with no Ruby knowledge, but to take full advantage of nanoc, you’ll need to know Ruby well. I recommend the Programming Ruby book to people who don’t have a lot of Ruby experience yet.

Creating a Site

nanoc is a command-line application. This means that in order to use nanoc, you have to type geeky commands into a terminal all day. Hey, that’s the way all cool apps work.

A nanoc-powered site is a directory with a specific structure. In this tutorial, we’ll create a site named tutorial. To create this site, type into the terminal:

% nanoc create_site tutorial

If you did that right, you should see something like this in the terminal:

% nanoc create_site tutorial
      create  config.yaml
      create  Rakefile
      create  Rules
      create  content/index.html
      create  content/stylesheet.css
      create  layouts/default.html
Created a blank nanoc site at 'tutorial'. Enjoy!
% 

The nanoc-powered site named tutorial has now been created. Go into the directory and list the files there. You should see something like this:

% cd tutorial
tutorial% ls -l
total 24
-rw-r--r--  1 ddfreyne  staff   22 Feb 17 14:44 Rakefile
-rw-r--r--  1 ddfreyne  staff  692 Feb 17 14:44 Rules
-rw-r--r--  1 ddfreyne  staff  100 Feb 17 14:44 config.yaml
drwxr-xr-x  4 ddfreyne  staff  136 Feb 17 14:44 content
drwxr-xr-x  3 ddfreyne  staff  102 Feb 17 14:44 layouts
drwxr-xr-x  3 ddfreyne  staff  102 Feb 17 14:44 lib
drwxr-xr-x  2 ddfreyne  staff   68 Feb 17 14:44 output
tutorial% 

What all those files and directories are for will all become clear soon.

Compiling the Site

Before doing anything else, make sure the current working directory is the site you just created. All nanoc commands, except for create_site, require the current working directory to be a nanoc site. So, if you haven’t done it before:

% cd tutorial
tutorial%

Every new nanoc site already has a bit of content. It comes with one simple page with some simple “getting started” instructions. Before you can view the site, it needs to be compiled. To compile the site, do this:

tutorial% nanoc compile

Or, if you want it short, just type nanoc:

tutorial% nanoc

This is what’ll appear in the terminal while nanoc is compiling:

tutorial% nanoc compile
Loading site data…
Compiling site…
      create  [0.01s] output/index.html

Site compiled in 0.01s.
tutorial% 

A file named index.html has been created in the output directory. Start a web server using the view command, like this:

tutorial% nanoc view

Now, open your web browser and navigate to http://localhost:3000/. What you’ll see is something like this:

(If you open the index.html directly in your web browser, the stylesheet will most likely not be loaded. This is because the page has an absolute link to the style.css file, not a relative one.)

You can also open the output/index.html file in your favourite text editor, where you’ll find that the file is just a normal HTML page.

Editing the Home Page

The first step in getting to know how nanoc really works will involve editing the content of the home page. First, though, a quick explanation of how uncompiled pages are stored.

The pages in a nanoc site are stored in the content directory. Currently, that directory has only two files: index.html and stylesheet.css. The first file forms the home page, while the second file is the stylesheet. If you open the index.html file, you’ll notice a section containing metadata in YAML format at the top.

Let’s change the content of the home page. Open index.html and add a paragraph somewhere in the file. I recommend something like this:

<p>This is a brand new paragraph which I've just inserted into this file! Gosh, I can barely control my excitement!</p>

To view the changes, the site must be recompiled first. So, run the compile command. You should see something like this:

tutorial% nanoc compile
Loading site data…
Compiling site…
      update  [0.01s] output/index.html

Site compiled in 0.01s.
tutorial% 

The number between brackets next to the output/index.html filename indicates the time it took for nanoc to compile the home page. At the bottom, the total time needed for compiling the entire site is also shown.

Make sure that the preview server (nanoc view) is still running, reload http://localhost:3000/ in your browser, and verify that the page has indeed been updated.

In the same file, let’s change the page title from “Home” to something more interesting. Change the line that reads title: "Home" to something else. The file should now start with this:

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

The metadata section at the top of the file is formatted as YAML. All attributes are free-form; you can put anything you want in the attributes: the page title, keywords relevant to this page, the name of the page’s author, the language the page is written in, etc.

Recompile the site and once again load http://localhost:3000/ in your browser. You will see that the browser’s title bar displays the page’s title now. If you’re wondering how exactly nanoc knew that it had to update the stuff between the <title> and </title> tags: don’t worry. There’s no magic involved. It’ll all become crystal clear in a minute. (Take a peek at layouts/default.html if you’re curious.)

Adding a Page

In nanoc, pages are sometimes referred to as “items.” This is because items don’t necessarily have to be pages: JavaScript and CSS files aren’t pages, but they are items.

To create a new page or item in the site, use the create_item command (or ci for short). Let’s create an “about” page like this:

tutorial% nanoc create_item about

You should see this:

tutorial% nanoc create_item about
      create  content/about.html
tutorial% 

Open the newly generated file and put some text in it, like this (be sure to leave the metadata section intact):

<h1>My cute little "About" page</h1>

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

In the metadata section, change the title to something else:

title: "My Cool About Page"

Recompile the site, and notice that a file output/about/index.html has been created. With the preview server running, open http://localhost:3000/about/ in your browser and admire your brand new about page. Shiny!

By the way, if you don’t like having a metadata section at the top of every page (perhaps because it breaks syntax highlighting), you can put the metadata in a YAML file with the same name as the page itself. For example, the content/about.html page could have its metadata stored in content/about.yaml instead.

Customizing the Layout

The default home page recommended editing the default layout, so let’s see what we can do there.

As you probably have noticed already, the page’s content files are not complete HTML files—they are partial HTML files. A page needs <html>, <head>, <body>, … elements before it’s valid HTML. This doesn’t mean you’ve been writing invalid HTML all along, though, because nanoc layouts each page as a part of the compilation process.

Take a look at the default.html file in the layouts directory. Just like items, it contains a metadata section at the top of the file. Open it in your text editor. It almost looks like a HTML page, with the exception of this piece of code:

…
<div id="main">
  <%= yield %>
</div>
…

The odd construct in the middle of that piece of code is an embedded Ruby instruction. The <%= yield %> instruction will be replaced with the item’s compiled content when compiling.

If you are not familiar with embedded Ruby (also known as eRuby), take a look at the eRuby article on Wikipedia, or the Embedding Ruby in HTML section of the Ruby and the Web chapter of the online Programming Ruby book.

The is another important piece of embedded Ruby code near the top of the file:

<title>A Brand New nanoc Site - <%= @item[:title] %></title>

This is where the page’s title is put into the compiled document.

Every page can have arbitrary metadata associated with it. To demonstrate this, add the following line to the metadata section of the about page:

author: "John Doe"

Now output the author name in the layout. Put this piece of code somewhere in your layout (somewhere between the <body> and </body> tags, please, or you won’t see a thing):

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

Recompile the site, and load http://localhost:3000/about/ in your browser. You’ll see that the about page has a line saying This page was written by John Doe, while the home page does not—as expected!

Writing Pages in Markdown

You don’t have to write pages in HTML. Sometimes, it is easier to use another language which can be converted to HTML instead. In this example, we’ll use Markdown to avoid having to write HTML. nanoc calls these text transformations filters.

Get rid of the content of the home page (content/index.html) and replace it with the following Markdown-formatted text (but leave the metadata section intact):

A First Level Header
====================

A Second Level Header
---------------------

Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.

The quick brown fox jumped over the lazy
dog's back.

### Header 3

> This is a blockquote.
> 
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote

To tell nanoc to format the home page as Markdown, let nanoc run it through the kramdown filter. For this, the Rules file is used. This file specifies all processing instructions for all items. It consists of a series of rules, which in turn consist of three parts:

rule type

This can be compile (which specifies the filters and layouts to apply), route (which specifies where a compiled page should be written to) or layout (which specifies the filter to use for a given layout).

selector

This determines what items or layouts the rule applies to. It can contain the * wildcard, which matches anything. The default rules file has three rules of each type, and they all apply to all items or layouts.

instructions

This is the code inside the do…end block and specifies what exactly should be done with the items that match this rule.

These rules are quite powerful and are not fully explained in this tutorial. I recommend checking out the manual for a more in-depth explanation of the rules file.

Take a look at the default compilation rule (the compile '*' do … end one). This rule applies to all items due to the * wildcard. When this rule is applied to an item, the item will first be filtered through the erb filter and will then be laid out using the default layout.

To make sure that the home page (but not any other page) is run through the kramdown filter, add this piece of code before the existing compilation rule:.

compile '/' do
  filter :kramdown
  layout 'default'
end

It is important that this rule comes before the existing one (compile '*' do … end). When compiling a page, nanoc will use the first and only the first matching rule; if the new compilation rule were below the existing one, it would never have been used.

Now that we’ve told nanoc to filter this page using kramdown, let’s recompile the site. The output/index.html page source should now contain this text (header and footer omited):

<h1>A First Level Header</h1>

<h2>A Second Level Header</h2>

<p>Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.</p>

<p>The quick brown fox jumped over the lazy
dog's back.</p>

<h3>Header 3</h3>

<blockquote>
    <p>This is a blockquote.</p>

    <p>This is the second paragraph in the blockquote.</p>

    <h2>This is an H2 in a blockquote</h2>
</blockquote>

The kramdown filter is not the only filter you can use—take a look a the full list of filters included with nanoc. You can also write your own filters—read the Writing Filters section in the manual for details.

Writing some Custom Code

There is a directory named lib in your nanoc site. In there, you can throw Ruby source files, and they’ll be read and executed before the site is compiled. This is therefore the ideal place to define helper methods. 

As an example, let’s add some tags to a few pages, and then let them be displayed in a clean way using a few lines of custom code. Start off by giving the “about” page some tags. Open about.html and add this to the meta section:

tags:
  - foo
  - bar
  - baz

Next, create a file named tags.rb in the lib directory (the filename doesn’t really matter). In there, put the following function:

def tags
  if @item[:tags].nil?
    '(none)'
  else
    @item[:tags].join(', ')
  end
end

This function will take the current page’s tags and return a comma-separated list of tags. If there are no tags, it returns “(none)”. To put this piece of code to use, open the default layout and add this line right above the <%= yield %> line:

<p>Tags: <%= tags %></p>

Recompile the site, and take a look at both HTML files in the output directory. If all went well, you should see a list of tags right above the page content.

Writing your own functions for handling tags is not really necessary, though, as nanoc comes with a tagging helper by default. To enable this tagging helper, first delete tags.rb and create a helper.rb file (again, the filename doesn’t really matter) and put this inside:

include Nanoc::Helpers::Tagging

This will make all functions defined in the Nanoc::Helpers::Tagging module available for use. You can check out the API documentation for the Tagging helper, but there is only one function we’ll use: tags_for. It’s very similar to the tags function we wrote before. Update the layout with this:

<p>Tags: <%= tags_for(@item) %></p>

Now compile the site again, and you’ll see that nanoc shows the tags for the page, but this time using the built-in tagging helper.

nanoc comes with quite a few useful helpers. The API documentation describes each one of them.

That’s it!

This is the end of the tutorial. I hope that this tutorial both whet your appetite, and gave you enough information to get started with nanoc.

There’s more reading material. It’s definitely worth checking out the following chapters; they’re rather big, but they contains everything you need to know about nanoc.