1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

Making the Jump from nanoc 2.2 to nanoc 3.0
===========================================

nanoc 3.0 is quite different from nanoc 2.2 in several ways. It is not
backward compatible, which means that it is not possible to compile a nanoc
2.2 site out of the box. This document is meant to be a guide through the
steps necessary to convert a nanoc 2.2 site to a nanoc 3.0 one.

Getting nanoc 3.0
-----------------

At the moment, there is no package for nanoc 3.0 yet. To get nanoc, clone the
repository (http://projects.stoneship.org/hg/nanoc/) using Mercurial, cd into
the nanoc directory and execute the 'gem:install' rake task as root.

Dropped Features
----------------

Several features present in nanoc 2.2 are no longer supported in nanoc 3.0.
These include:

* Support for binary assets
* Support for drafts
* Support for templates
* save_*, delete_*, move_* methods in data sources
* Old-style routers (replaced with routing rules---see below for details)
* Page and asset defaults

Items versus Pages and Assets
-----------------------------

Pages and textual assets have been merged and are now known simply as "items."
This means that all operations on pages can now be applied to textual assets
as well (such as laying out an asset, which was not possible before). Binary
assets are no longer supported.

Paths versus identifiers
------------------------

The _identifier_ of an item is a path starting with a slash and ending with a
slash. It is not necessarily the path that will be used when linking to this
item.

The _path_ of an item is the path that will be used when linking to the item.
It can be identical to the identifier, but it does not have to be. The path
does not include any trailing index file names (as specified in the site
configuration).

The _raw path_ of an item is the path, relative to the current working
directory, to the output file. It includes the path to the output directory
and it also includes the trailing index filename (if any).

Accessing attributes
--------------------

Accessing item attributes is now done using the #[] method (e.g.
`@item[:title]`). It is no longer possible to use "dot notation" to request
attributes (e.g. `@item.title` will not work).

Rules
-----

nanoc 3.0 does not use attributes in metadata files (the `.yaml` files) in
order to figure out how to compile a page. Instead, processing instructions
are located in a new file called `Rules` which lives at the top level of the
nanoc site directory.

The file contains three different kinds of rules: routing rules, compilation
rules and layouting rules. Compilation rules determine the actions that should
be executed during compilation (filtering, layouting), while routing rules
determine the path where the compiled files should be written to.

A rule consists of a selector, which identifies which items the rule should be
applicable to, and an action block, which contains the actions to perform.

nanoc will first attempt to build a route for each item. To do so, it will run
through all items and find the first matching rule for each item. Only the
first matching rule will be used; matching rules that come later will be
ignored. Once all items are routed, nanoc will run through all items and find
the first matching compilation rule and apply that to the relevant item.

### Routing Rules

A routing rule looks like this:

    route '/foo/' do |rep|
      # ... 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.

The block argument contains the item representation that is currently being
routed (not the item).

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

Example #1: The following rule will give the item with identifier `/404/` the
path `/error/404.php` (in nanoc 2.2, this would have been done using the
`custom_path` attribute):

    route '/404/' do |rep|
      '/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|
      rep.item.identifier + 'index.html'
    end

TODO write me

### Compilation Rules

TODO write me

### Layouting Rules

To specify the filter used for a layout, use the `#layout` method. This method
takes a hash with one key and one pair.

The key 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 value should be the identifier of the filter to use.

Example: The following rule would make all layouts use the `:erb` filter:

    layout '*' => :erb