Help » Tutorial
(If you already have a bit of experience with nanoc, you may find the Manual a very useful resource in addition to this tutorial.)
Installing nanoc ¶
nanoc requires Ruby (1.8.5 or higher required). nanoc also requires RubyGems. You may already have RubyGems installed, but if you don’t, get it here.
Once you have RubyGems, installing nanoc is easy. Simply write this in your terminal:
sudo gem install nanoc
Requirements for this Tutorial ¶
This tutorial requires RedCloth. RedCloth is a Ruby implementation of both Textile and Markdown, which both allow you to write HTML in a easy-to-use plain text format. In this tutorial, we’ll use Markdown. (If you haven’t used Markdown before, don’t fear—it’s easy.) To install RedCloth, jump to your terminal and type:
sudo gem install RedCloth
You can also use BlueCloth (which only handles Markdown) instead of RedCloth for this tutorial, but there unfortunately seems to be an incompatibility between BlueCloth and Ruby 1.9.
Creating your First nanoc-powered 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 (or maybe not). It also explains why nanoc doesn’t have any screenshots.
A nanoc-powered site is a directory with a specific structure. You can create such a directory yourself, but the best way is to let nanoc do it for you. In this tutorial, we’ll create a site named nanoc_test. To create this site, type into the terminal:
nanoc create_site nanoc_test
If you did that right, you should have seen this appear on the screen:
create output create config.yaml create Rakefile create tasks create tasks/default.rake create content create content/content.txt create content/content.yaml create meta.yaml create templates/default create templates/default/default.txt create templates/default/default.yaml create layouts create layouts/default.erb create lib create lib/default.rb
The nanoc-powered site named nanoc_test has now been created. Go into the directory and list the files there. You should see something like this:
-rw-r--r-- 1 ddfreyne ddfreyne 123 14 Dec 09:19 Rakefile -rw-r--r-- 1 ddfreyne ddfreyne 48 14 Dec 09:19 config.yaml drwxr-xr-x 9 ddfreyne ddfreyne 306 14 Dec 10:49 content drwxr-xr-x 3 ddfreyne ddfreyne 102 14 Dec 09:19 layouts drwxr-xr-x 3 ddfreyne ddfreyne 102 14 Dec 09:19 lib -rw-r--r-- 1 ddfreyne ddfreyne 322 14 Dec 10:37 meta.yaml drwxr-xr-x 9 ddfreyne ddfreyne 306 14 Dec 10:50 output drwxr-xr-x 3 ddfreyne ddfreyne 102 14 Dec 09:19 tasks drwxr-xr-x 3 ddfreyne ddfreyne 102 14 Dec 09:19 templates
What all those directories are for, will be explained in just a minute, step by step.
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.
A new nanoc site isn’t completely empty. It comes with one extremely minimalistic homepage, as well as one extremely minimalistic layout used by this homepage.
Before you can view the site, it needs to be compiled. All pages are stored in uncompiled source form in the site directory (in content, to be precise, as you will see in a bit). To compile the site, do this:
nanoc compile
This is what’ll appear in the terminal when nanoc is done compiling:
Compiling site...
create output/index.html
Site compiled in 0.02s.
A file named index.html has been created in the output directory. Open it in your favourite web browser (mine is Safari); what you’ll see is a very simple web page that says I’m a brand new root page. Please edit me!
. If you doubt that it’s an actual HTML page, open the file in your favourite text editor (mine is TextMate) and check out the page source.
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: content.txt and content.yaml. These two files together form the home page. The file ending with .yaml specifies the page’s attributes (metadata, properties, whatever you want to call it), while the other file contains the actual page content. This may sound confusing, but it’ll make more sense once more pages are added to the site. Patience, young padawan.
Let’s change the homepage content to something less generic. Open content.txt and change its text to something more exciting, perhaps something like this:
<p>Welcome to my new nanoc site! Denis is my hero!</p>
To view the changes, the site must be recompiled first. So, do this:
nanoc compile
And this is what you’ll see:
Compiling site...
update output/index.html
Site compiled in 0.02s.
Open index.html in the output directory in your web browser and your text editor again, and verify that the page has indeed been updated.
One thing that hasn’t changed is the page title—the title that appears in the browser’s title bar. The page title is defined in the page’s meta file. Such a meta file contains all metadata about the page, e.g. the layout that should be used for this page, the page title, the page’s author, when this page was created, … The homepage meta file, content.yaml, looks like this right now:
# Built-in # Custom title: "A New Root Page"
This file is split into two sections: Built-in and Custom. In the Built-in section, you can put metadata that is used by nanoc itself. For example, the layout attribute is used to determine which layout this page uses. There’s a full list of built-in attributes in chapter 2 of the manual.
The Custom section is for custom metadata that isn’t used by nanoc. Any attributes that aren’t built-in are custom. Custom metadata could include the page title, keywords relevant to this page, the name of the page’s author, the language the page is written in, etc.
The homepage’s meta file currently has one attribute, title. Change this to something cooler, like this:
title: "The Guild of nanoc: a fan website dedicated to nanoc"
Recompile the site and open index.html in your browser. You will see that the browser’s title bar displays the page’s title now. There’s no magic involved here—it’ll all become clear in a minute (or you can already take a peek at layouts/default.erb if you can’t wait).
Adding a Page ¶
To create a new page in the site, use the create_page command. Let’s create an “about” page like this:
nanoc create_page about
You should see this:
create content/about create content/about/about.yaml create content/about/about.txt
There is now a content/about directory, with two files in it: the content file and the meta file. Open the content file (content/about/about.txt) and put some text in it, like this:
<p>This is the about page for my new nanoc site.</p>
Edit the meta file (the YAML one) so it looks like this:
# Built-in # Custom title: "The Guild of nanoc -- About the Guild"
Recompile the site, and notice that a file output/about/index.html has been created. Open that file in your web browser, and admire your brand new about page.
Customizing the Layout ¶
As you probably have noticed already, the page’s content files are not really 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 in the layouts directory. It contains one file, default.erb. This is the layout used by the home page and the about page. Open default.erb in your favourite text editor. This is what it looks like:
<html>
<head>
<title><%= @page.title %></title>
</head>
<body>
<%= @page.content %>
</body>
</html>This file isn’t really HTML; it’s HTML with embedded Ruby source in it. When compiling a site, nanoc will take a page that needs to be compiled and put it in the @page variable. Then, it’ll evaluate the layout: <%= @page.title %> will be replaced by the page title, and <%= @page.content %> will be replaced by the page content. The compiled homepage will therefore look like this:
<html>
<head>
<titleThe Guild of nanoc: a fan website dedicated to nanoc</title>
</head>
<body>
<p>Welcome to my new nanoc site! Denis is my hero!</p>
</body>
</html>If you are not familiar with embedded Ruby (also known as eRuby), take a look at the eRuby info site, the eRuby article on Wikipedia, or the “Embedding Ruby in HTML” section of the “Ruby and the Web” chapter of Programming Ruby.
Let’s take this layout to a higher level. Remember being able to add custom metadata to any document? Let’s let the default layout display the value of the author metadata attribute. Currently, no document has author set, so we’ll take care of that in the layout. Here’s what the updated layout could look like:
<html>
<head>
<title><%= @page.title %></title>
</head>
<body>
<% unless @page.author.nil? %>
<p>This page was written by <%= @page.author %>.</p>
<% end %>
<%= @page.content %>
</body>
</html>Let’s set the page author for the “about” page. Open content/about/about.yaml and add the following line to the “custom” section:
author: "John Doe"
Recompile the site, and open the output/index.html and output/about/index.html pages in your browser. You’ll see that the about page has a line saying This page was written by John Doe.
—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.
Let’s get rid of the contents of the home page and replace it with some Markdown-formatted text. Open content/content.txt and put this in instead:
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 blockquoteIf you would compile the site now, the compiled HTML page won’t display the converted HTML just yet, because we haven’t told nanoc to filter this page as Markdown yet. Open the homepage’s meta file and add this line to the “built-in” section:
filters_pre: - "redcloth"
filters_pre is an attribute with a list of filters to run before laying out the page. You can also run filters after laying out the page, in which case you’d use filters_post. Chapter 2 of the manual has a list of built-in filters you can use.
Now that we’ve told nanoc to filters this page using RedCloth, let’s recompile the site. (If you are getting errors at this point, make sure you have RedCloth installed, as described at the beginning of this tutorial). The output/index.html page source should now look like this:
<html>
<head>
<titleThe Guild of nanoc: a fan website dedicated to nanoc</title>
</head>
<body>
<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>
</body>
</html>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.yaml and add this to the end of the “custom” section:
tags: - "foo" - "bar" - "baz"
Next, create a file named tags.rb in the lib directory. In there, put the following function:
def tags
if @page.tags.nil?
'(none)'
else
@page.tags.join(', ')
end
endThis 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 <%= @page.content %> 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.
This example may be a bit weak—after all, you could simply embed the tag-generating code into the layout directly, like this:
<p>Tags: <%= @page.tags.nil? ? '(none)' : @page.tags.join(', ') %></p>However, putting embedded Ruby code in HTML can get dirty pretty quickly. This example is still acceptable, but in cases where you need much larger amounts of code, it’s best to create a separate function and then call this function where necessary.
Watch out for Paths ¶
There’s one tricky thing involving paths that you need to know. To show you what can go wrong, let’s create a stylesheet named style.css in the output directory. Here’s what I put in there:
h1, h2, h3 { color: red; }To link the stylesheet to the web site, open the layout (default.erb) and put this in:
<link href="style.css" rel="stylesheet" type="text/css">When you compile the site now and open index.html, you’ll see that all headers are red. about/index.html’s headers, however, are not styled—the web browser looks for a about/style.css which doesn’t exist.
The most elegant solution is to use an absolute path, like this (note the new slash):
<link href="/style.css" rel="stylesheet" type="text/css">The compiled files in the output directory will definitely not be styled now if you open them by double-clicking, but that’s okay—when the site is put on your web server, web browsers will find the stylesheet.
This would mean that you can’t preview your site locally anymore, but there’s a neat solution for that too. nanoc comes with an auto-compiler, which is a web server that compiles pages on-the-fly. More importantly, the output directory is its web root, so absolute paths are no issue anymore. To start it:
nanoc aco
This starts a server on localhost, port 3000 (you can customize the port with -p if you want). Now you can go to http://localhost:3000/ and absolute paths will pose no problem anymore.
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 Manual—it’s rather big, but it contains everything you need to know about nanoc.