Variables

At several moments in the compilation process, Nanoc exposes several variables containing site data. These variables take the appearance of Ruby instance variables, i.e. prefixed with an @ sigil (e.g. @items).

The following variables exist:

@item_rep

@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.

There are three contexts in which variables are exposed: in the preprocess/postprocess block, within compile and route rules, and during filtering/layouting.

@config

The @config variable contains the site configuration, read from nanoc.yaml or config.yaml.

@config[:some_key] → object

The attribute for the given key, or nil if the key is not found.

@config.fetch(:some_key, fallback) → object

The attribute for the given key, or fallback if the key is not found.

@config.fetch(:some_key) { |key| … } → object

The attribute for the given key, or the value of the block if the key is not found.

@config.key?(:some_key) → true / false

Whether or not an attribute with the given key exists.

The following methods are available during preprocessing:

@config[:some_key] = some_value → nothing

Assigns the given value to the attribute with the given key.

@items and @layouts

The @items variable contains all items in the site. Similarly, @layouts contains all layouts.

@items[arg] → object

@layouts[arg] → object

The single item or layout that matches given argument, or nil if nothing is found.

@items.each { |item| … } → nothing

@layouts.each { |item| … } → nothing

Yields every item or layout.

@items.find_all(arg) → collection of items

@layouts.find_all(arg) → collection of layouts

All items or layouts that match given argument.

@items.size → Integer

@layouts.size → Integer

The number of items.

Both @items and @layouts include Ruby’s Enumerable, which means useful methods such as #map and #select are available.

To find an item or layout by identifier, passing the identifier to the #[] method:

@items["/about.md"]

You can also pass a string pattern (a glob) to #[] to find an item or layout whose identifier matches the given string:

@layouts["/default.*"]

Additionally, you can pass a regular expression to the #[] method, which will find the item or layout whose identifier matches that regex:

@items[%r{\A/articles/2014/.*}]

The #find_all method is similar to #[], but returns a collection of items or layouts, rather than a single result.

The following methods are available during preprocessing:

@items.delete_if { |item| … } → nothing

@layouts.delete_if { |layout| … } → nothing

Removes any item or layout for which the given block returns true.

@items.create(content, attributes, identifier) → nothing

@items.create(content, attributes, identifier, binary: true) → nothing

@layouts.create(content, attributes, identifier) → nothing

Creates an item with the given content, attributes, and identifier. For items, if the :binary parameter is true, the content will be considered binary.

@item

The @item variable contains the item that is currently being processed. This variable is available within compilation and routing rules, as well as while filtering and laying out an item.

@item[:someattribute] → object

The attribute for the given key.

@item.attributes → Hash

A hash containing all attributes of this item.

@item.binary? → true / false

Whether or not the source content of this item is binary.

@item.compiled_content → String

@item.compiled_content(rep: :foo) → String

@item.compiled_content(snapshot: :bar) → String

The compiled content. The :rep option specifies the item representation (:rep by default), while :snapshot specifies the snapshot (:last by default). This method cannot be used in the preprocessor or the rules, as the content has not been (fully) compiled at that point.

@item.fetch(:some_key, fallback) → object

The attribute for the given key, or fallback if the key is not found.

@item.fetch(:some_key) { |key| … } → object

The attribute for the given key, or the value of the block if the key is not found.

@item.identifier → identifier

The identifier, e.g. /about.md, or /about/ (with legacy identifier format).

@item.key?(some_key) → true / false

Whether or not an attribute with the given key exists.

@item.path → String

@item.path(rep: :foo) → String

@item.path(snapshot: :bar) → String

The path to the compiled item, without the index filename (e.g. if the item rep is routed to /foo/index.html, the path will be /foo/). The :rep option specifies the item representation (:rep by default), while :snapshot specifies the snapshot (:last by default).

@item.raw_filename → String / nil

The path to the file containing the uncompiled content of this item.

@item.reps → collection of reps

The collection of representations for this item.

For items that use the legacy identifier format (e.g. /page/ rather than /page.md), the following methods are available:

@item.parent → item / nil

The parent of this item, i.e. the item that corresponds with this item’s identifier with the last component removed. For example, the parent of the item with identifier /foo/bar/ is the item with identifier /foo/.

@item.children → collection of items

The items for which this item is the parent.

The following methods are available during preprocessing:

@item[:some_key] = some_value → nothing

Assigns the given value to the attribute with the given key.

@item.update_attributes(some_hash) → nothing

Updates the attributes based on the given hash.

The item reps collection (@item.reps) has the following methods:

@item.reps[:name] → item rep / nil

The item representation with the given name, or nil if the requested item rep does not exists.

@item.reps.each { |rep| … } → nothing

Yields every item representation.

@item.reps.fetch(:name) → item rep

The item representation with the given name. Raises if the requested item rep does not exist.

@item.reps.size → Integer

The number of item representations.

The following methods are available during postprocessing:

@item.modified? → boolean

true if the item’s compiled content has changed; false otherwise.

Item representation collections include Ruby’s Enumerable, which means useful methods such as #map and #select are available.

@layout

The @layout variable contains the layout that is currently being used. This variable is only available while laying out an item.

@layout[:someattribute] → object

The attribute for the given key.

@layout.attributes → Hash

A hash containing all attributes of this layout.

@layout.fetch(:some_key, fallback) → object

The attribute for the given key, or fallback if the key is not found.

@layout.fetch(:some_key) { |key| … } → object

The attribute for the given key, or the value of the block if the key is not found.

@layout.identifier → identifier

The identifier, e.g. /about.md, or /about/ (with legacy identifier format).

@layout.key?(some_key) → true / false

Whether or not an attribute with the given key exists.

The following methods are available during preprocessing:

@layout[:some_key] = some_value → nothing

Assigns the given value to the attribute with the given key.

@layout.update_attributes(some_hash) → nothing

Updates the attributes based on the given hash.

@item_rep or @rep

The @item_rep variable contains the item representation that is currently being processed. It is also available as @rep. This variable is available while filtering and laying out an item.

@item_rep.binary? → true / false

Whether or not the content of the :last snapshot of this item representation is binary.

@item_rep.item → item

The item for the item rep.

@item_rep.name → Symbol

The name of the item rep, e.g. :default.

@item_rep.path → String

@item_rep.path(snapshot: :foo) → String

The path to the compiled item representation, without the index filename (e.g. if it is routed to /foo/index.html, the path will be /foo/). The :snapshot specifies the snapshot (:last by default).

@item_rep.raw_path → String

@item_rep.raw_path(snapshot: :foo) → String

The full path to the compiled item representation, including the path to the output directory and the index filename (e.g. if it is routed to /foo/index.html, the raw path might be /home/denis/mysite/output/foo/index.html). The :snapshot specifies the snapshot (:last by default).

@item_rep.compiled_content → String

@item_rep.compiled_content(snapshot: :bar) → String

The compiled content. The :snapshot specifies the snapshot (:last by default).