Basic Concepts

% nanoc command

% nanoc help command

% nanoc help create_site
nanoc create_site [path]

aliases: cs

create a site

    Create a new site at the given path. The site will use the compact
    filesystem data source by default, but this can be changed by
    using the --datasource commandline option.

options:

   -d --datasource specify the data source for the new site

% nanoc help

Selecting a different version

By default, nanoc will invoke nanoc 3.x. If you want to use nanoc 2.x instead, you can select this version using the nanoc-select commandline tool, which works like this:

% nanoc-select 3
Switched to nanoc version 3.

% nanoc --version
nanoc 3.1.0 (c) 2007-2010 Denis Defreyne.
Ruby 1.9.1 (2010-01-10) running on i386-darwin10.2.0

% nanoc-select 2
Switched to nanoc version 2.

% nanoc --version
nanoc 2.2.3 (c) 2007-2010 Denis Defreyne.
Ruby 1.9.1 (2010-01-10) running on i386-darwin10.2.0

Creating a Site

To create a site, use the create_site command. This command takes the site name as its first and only argument, like this:

% nanoc create_site site_name

This will create a directory with the given site name, with a bare-bones directory layout.

Structure

A site has the following files and directories:

config.yaml

contains the site configuration

Rules

contains compilation, routing and layouting rules

content/

contains the uncompiled items

layouts/

contains the layouts

lib/

contains custom site-specific code (filters, helpers, …)

output/

contains the compiled site

tmp/

contains data used for speeding up compilation (can be safely emptied)

Code

nanoc will load all Ruby source files in the lib directory before it starts compiling. All method definitions, class definitions, etc. will be available during the compilation process. This directory is therefore quite useful for putting in site-wide helpers, filters, data sources, etc.

Site configuration

The site configuration is defined by the config.yaml file at the top level of the site directory. The file is in YAML format. The configuration has the following predefined values (check the API documentation for Nanoc3::Site for details about the default values):

text_extensions

A list of file extensions that nanoc will consider to be textual rather than binary. If an item with an extension not in this list is found, the file will be considered as binary.

output_dir

The path to the directory where all generated files will be written to. This can be an absolute path starting with a slash, but it can also be path relative to the site directory.

index_filenames

A list of index filenames, i.e. names of files that will be served by a web server when a directory is requested. Usually, index files are named “index.hml”, but depending on the web server, this may be something else, such as “default.htm”. This list is used by nanoc to generate pretty URLs.

enable_output_diff

Whether or not to generate a diff of the compiled content when compiling a site. The diff will contain the differences between the compiled content before and after the last site compilation.

data_sources

The data sources where nanoc loads its data from. This is an array of hashes; each array element represents a single data source. By default, there is only a single data source that reads data from the “content/” and “layout/” directories in the site directory. See below for details.

watcher

Configuration for the “watch” command, which watches a site for changes and recompiles if necessary. See below for details.

The data source configuration is an array of hashes with the following keys:

type

The type is the identifier of the data source. By default, this will be filesystem_unified.

items_root

The path where items should be mounted (comparable to mount points in Unix-like systems). This is “/” by default, meaning that items will have “/” prefixed to their identifiers. If the items root were “/en/” instead, an item at content/about.html would have an identifier of “/en/about/” instead of just “/about/”.

layouts_root

The path where layouts should be mounted. The layouts root behaves the same as the items root, but applies to layouts rather than items.

(Auto)compiling a Site

To compile a site to its final form, the nanoc compile (or nanoc co) command is used. This will write the compiled site to the output directory as specified in the site configuration file. For example:

% nanoc co

nanoc will not compile items that are not outdated. You can tell nanoc to compile all items to pass the --force or -f flag. Also useful is the --verbose or -V flag, which turns on extra output.

It is possible to let nanoc run a local web server, the autocompiler, that serves the nanoc site. Each request will cause the requested item to be compiled on the fly before being served. To run the autocompiler, use nanoc autocompile or nanoc aco. The autocompiler will run on port 3000 by default; this can be changed using the --port commandline switch. Note that this autocompiler should only be used for development purposes to make writing sites easier; it is quite unsuitable for use on live servers.

text_extensions: [ 'css', 'erb', 'haml', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'php', 'rb', 'sass', 'txt' ]

Creating an Item

Items are stored as plaintext files on the hard drive (unless you’re using esoteric data sources), so it’s easy to manually create items. nanoc provides a create_item (or ci) command for making item generation easier, though. This command looks like this:

% nanoc create_item item_identifier

Attributes

Each item has attributes (metadata) associated with it. This metadata consists of key-value pairs, which are stored in YAML format (although this may vary for different data sources). All attributes are free-form; there are no predefined attributes.

Some filters or helpers may use certain attributes. When using such filters or helpers, be sure to check their documentation (see below) to see what attributes they use, if any.

When using a filesystem-based data source, attributes are stored as YAML in either the top of the file representing the item, or a separate file with the same base name. For example, an item at content/about.html could look like this when the metadata is embedded into the file:

---
title: "Some Page"
---

<p>Lorem ipsum dolor sit amet...</p>

If you are using the default data source (filesystem_unified), then each item will automatically receive some extra attributes that may be useful. These are:

:filename

the name of the file corresponding to the item (if there is only one file that contains both content and metadata)

:content_filename

the name of the content file (if there is a content file)

:meta_filename

the name of the meta-file (if there is a meta-file)

:extension

the extension of the file or the content file (if there is one, because it is possible to have a meta-file without a corresponding content file)

Representations

An item representation (or “rep” for short) is a compiled version of an item. Each representation has a name (a symbol, not a string). An item can have multiple representations, though usually it will have just one (named default).

Multiple representations are useful when items need to be available in multiple formats. For example, HTML and XHTML. You could also have a raw representation that isn’t compiled at all—just the raw, unfiltered, non-laid out content. Sometimes, it may even be useful to have XML, YAML or JSON representations of an item.

An item’s list of representation can be fetched by calling Nanoc3::Item#reps instance. To get a specific rep, use Nanoc3::Item#rep_named with the rep name, like this:

rep = @item.rep_named(:default)

Snapshots

A snapshot is the compiled content at a specific point during the compilation process. Snapshots can be generated manually, but some snapshots are generated automatically (see below).

To get the compiled content of a specific snapshot, use the :snapshot option of Nanoc3::Item#compiled_content or Nanoc3::ItemRep#compiled_content. For example:

stuff = some_item.compiled_content(:snapshot => :pre)
stuff = some_rep.compiled_content(:snapshot => :last)

The following snapshots are generated automatically:

:raw

The content right before actual compilation is started

:pre

The content right before the item is laid out

:post

The content after the item has been laid out and post-filtered

:last

The most recent compiled content

The :post and :last snapshots will usually be the same. The difference is that :last is a moving snapshot: it always refers to the last compiled content. :last may refer to :raw or :pre early on, but may point to :post later. Also, there will always be a :last snapshot but not necessary a :post snapshot; items that are not laid out will not have one.

Binary items cannot have snapshots.

Variables

When compiling items with filters that support adding code to the item or the layout (such as ERB and Haml), several variables are made available. These variables are:

@item_rep

The item representation that is currently being compiled.

@item

The item that is currently being compiled.

@items

The list of all items, including ones that have not yet been compiled.

@layout

The layout that is currently being used in the layout phase.

@layouts

The list of all layouts.

@config

The site configuration as a hash.

@site

The site.

To get an item attribute, use the Nanoc3::Item#[] method and pass the attribute key as a symbol, e.g. @item[:author].

<html>
  <head>
    <title><%=h @item[:title] %></title>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

As Partials

Layouts can also be used as partials: a specific layout can be rendered into an item or a layout by using the render function, which takes the layout name as an argument. For example:

<%= render 'head' %>

To use this helper, activate the Rendering helper (see the helpers section for details), which is done by adding this line of code to some file in the lib directory (I recommend lib/helpers.rb):

include Nanoc3::Helpers::Rendering

It is also possible to pass custom variables to rendered partials by putting them into a hash passed to #render. The following example will make a @title variable (set to "Foo" in this example) available in the head layout:

<%= render "head", :title => "Foo" %>

Routing Rules

A routing rule looks like this:

route '/foo/' do
  # (routing code here)
end

The argument for the #route method is the identifier of the item that should be compiled. It can also be a string that contains the * wildcard, which matches zero or more characters. Additionally, it can be a regular expression.

A :rep argument can be passed to the #route call. This indicates the name of the representation this rule should apply to. This is :default by default, which means routing rules apply to the default representation unless specified otherwise.

The code block should return the routed path for the relevant item. The code block can return nil, in which case the item will not be written.

In the code block, you have access to @rep, which is the item representation that is currently being processed, and @item, which is an alias for @rep.item.

Example #1: The following rule will give the item with identifier /404/ the path /error/404.php:

route "/404/" do
  "/errors/404.php"
end

Example #2: The following rule will give all identifiers for which no prior matching rule exists a path based directly on its identifier (for example, the item /foo/bar/ would get the path /foo/bar/index.html):

route "*" do
  rep.item.identifier + "index.html"
end

Example #3: The following rule will prevent all items with identifiers starting with /links/, including the /links/ item itself, from being written (the items will still be compiled so that they can be included in other items, however):

route "/link/*" do
  nil
end

Example #4: The following rule will apply to all items below /people/, but not the /people/ item itself, and only to textual representations (with name equal to :text):

route "/people/*/", :rep => :text do
  item.identifier + ".txt"
end

Compilation Rules

A compilation rule looks like this:

compile "/foo/" do
  # (compilation code here)
end

The argument for the #compile command is exactly the same as the argument for #route; see above for details.

Just like with routing rules, a :rep argument can be passed to the #compile call. This indicates the name of the representation this rule should apply to. This is :default by default, which means compilation rules apply to the default representation unless specified otherwise.

The code block should execute the necessary actions for compiling the item. It does not have to return anything.

In the code block, you have access to @rep, which is the item representation that is currently being processed, and @item, which is an alias for @rep.item.

A compilation action can either be a filter action, a layout action, or a snapshot action.

To filter an item representation, call #filter pass the name of the filter as argument, along with any other filter arguments. For example, the following will call the :erb filter on the current item representation:

filter :erb

Additional parameters can be given to invocations of #filter. This is used by some filters, such as the Haml one (:haml), to alter filter behaviour in one way or another. For example, the following invokes the :haml filter with an additional parameter:

filter :haml, :format => :html5

To lay out an item representation, call #layout and pass the layout identifier as argument. For example, the following will lay out the item representation using the /default/ layout:

layout 'default'

You can run multiple filters and layouts sequentially, like this:

filter :erb
filter :kramdown
layout 'default'
filter :rubypants

To take a snapshot of an item representation, call #snapshot and pass the snapshot name as argument. For example, the following will create a :foo snapshot of the item representation that can later be referred to:

snapshot :foo

You’ll usually call #filter, #layout and #snapshot without explicit receiver, but you can also call them on the @rep object if you want. The following actions are equivalent:

filter :erb
@rep.filter :erb

layout 'default'
@rep.layout 'default'

snapshot :foo
@rep.snapshot :foo

Example #1: The following rule will not perform any actions, i.e. the item will not be filtered nor laid out:

compile '/sample/one/' do
end

Example #2: The following rule will filter the rep using the erb filter, but not lay out the rep:

compile '/samples/two/' do
  filter :erb
end

Example #3: The following rule will filter the rep using the erb filter, lay out the rep using the shiny layout, and finally run the laid out rep through the rubypants filter:

compile '/samples/three/' do
  filter :erb
  layout '/shiny/'
  filter :rubypants
end

Example #4: The following rule will filter the rep using the relativize_paths filter with the filter argument type equal to css:

compile '/assets/style/' do
  filter :relativize_paths, :type => :css
end

Example #5: The following rule will filter the rep and layout it by invoking #filter or #layout with an explicit receiver (with and without @ sign):

compile '/samples/three/' do
  @rep.filter :erb
  @rep.layout '/shiny/'
  @rep.filter :rubypants
end

Example #6: The following rule will apply to all items below /people/, and only to textual representations (with name equal to text):

compile '/people/*', :rep => :text do
  # don't filter or layout
end

Example #7: The following rule will create a snapshot named without_toc so that the content at that snapshot can then later be reused elsewhere:

compile '/foo/' do
  filter   :markdown
  snapshot :without_toc
  filter   :add_toc
end

Layouting Rules

To specify the filter used for a layout, use the #layout method.

The first argument should be a string containing the identifier of the layout. It can also be a string that contains the * wildcard, which matches zero or more characters. Additionally, it can be a regular expression.

The second should be the identifier of the filter to use.

In addition to the first two arguments, extra arguments can be supplied; these will be passed on to the filter.

Example #1: The following rule will make all layouts use the :erb filter:

layout '*', :erb

Example #2: The following rule will make the default layout use the haml filter and pass a filter argument:

layout '/default/', :haml, :format => :html5

Example #3: The following rule will be applied to all layouts with identifiers starting with a slash followed by an underscore, and ending with a slash. For example, “/foo/” and “/foo/_bar/” would not match, but “/_foo/”, “/_foo/bar/” and even “/_foo/_bar/” would:

layout %r{^/_.+/$}, :erb

Loading the Site Data

Before compilation starts, data for items and layouts will be read from all data sources, and mounted at the roots specified by the data sources. For more information about data sources, see the Data Sources section.

Preprocessing the Site Data

After the data is loaded, it is preprocessed if a preprocessor block exists. A preprocessor block is a simple piece of code defined in the Rules file that will be executed after the data is loaded. It looks like this:

preprocess do
  # (preprocessing code here)
end

Preprocessors can modify data coming from data sources before it is compiled. It can change item attributes, content and the path, but also add and remove items.

Preprocessors can be used for various purposes. Here are two sample uses:

• A preprocessor could set a language_code attribute based on the item path. An item such as /en/about/ would get an attribute language_code equal to 'en'. This would eliminate the need for helpers such as language_code_of.

• A preprocessor could create new (in-memory) items for a given set of items. This can be useful for creating pages that contain paginated items.

Building the Item Representations

Once the data is loaded and preprocessed, item representations are built for each item. For each item, its compilation rules (one per item representation) are looked up and a rep is built for each rule.

For example, the following code will cause the item /foo/ to have only one rep (default), while the item /bar/ will have two reps (raw and full):

compile '/foo/' do
  # (compilation code for the default rep here)
end

compile '/bar/', :rep => :raw do
  # (compilation code for the :raw rep here)
end

compile '/bar/', :rep => :full do
  # (compilation code for the :full rep here)
end

Routing the Item Representations

For each item representation, the matching routing rule is looked up and applied to the item rep. The item rep’s path to the output file will be set to the return value of the routing rule block.

The routing rule block can also return nil, in which case the item representation will not be written to the disk—useful when items should be included as part of other, larger items, but should not exist separately.

For example, the following code will cause the item /foo/ to be written to output/abc.html, while the /bar/ item will be written to output/xyz.css, and the item /qux/ will not be written at all:

route '/foo/' do
  '/abc.html'
end

route '/bar/' do
  '/xyz.css'
end

route '/qux/' do
  nil
end

Compiling the Item Representations

Compiling an item means compiling all of its representations, which in turn involves executing the compilation rules on each representation. After a compilation rule has been applied, the item representation’s compiled content will be written to its output file (if it has one) determined by its routing rule.

The following diagram illustrates item compilation by giving a few examples of how items can be filtered and laid out.

Items that have content dependencies on other items, i.e. items that include the content of another item, will be compiled once the content of the items it depends on is available. Circular content dependencies (item “A” requiring the content of item “B” and vice versa) are detected and reported.