Items and layouts

Items

Pages, such as an about page, and assets, such as a stylesheet or an image, are collectively called items.

An item has content, attributes, and an identifier.

Item content can be textual or binary. If the extension of the item is included in the site configuration’s text_extension list, it is considered to be textual; otherwise, it will be binary. Binary items don’t have their content stored in-memory. Instead, binary items have a filename pointing to the file containing the content.

Each item has attributes (metadata) associated with it. This metadata consists of key-value pairs. All attributes are free-form; there are no predefined attributes.

Some data sources set attributes on items by default. The filesystem data source, for example, sets content_filename and meta_filename, among others. Refer to the Filesystem data source section on the Data sources page for details.

Item representations

Every item has one or more item representations (or “reps” for short). An item representation is the compiled form of an item. Some examples of item representations:

  • an HTML representation, which will be the default for almost all sites
  • an RSS representation, useful for the home page for a blog
  • a JSON representation, so that the site can act as a read-only web API
  • a cue sheet representation, useful for track list pages

An item rep has a name, which usually refers to the format the content is in (html, json, rss, …). Unless otherwise specified, there will be a default representation, aptly named default.

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

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
:last
The most recent compiled content

Binary items cannot have snapshots.

Layouts

A layout is the “frame” for content to go into. Typically, a layout adds a header, and a footer to a page.

The following is a minimal layout that includes the content using yield, and emits some metadata:

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

An item is laid out using #layout function in a compilation rule. See the Rules page page for details.

Just like items, layouts have attributes and an identifier.

Partials

A layout can be used as a partial. A partial is a layout that is not used for laying out an item, but is rather intended to be included into another item or layout. Because of this, partials typically call yield.

To enable partials, first activate the rendering helper somewhere inside the lib/ directory, such as lib/helpers.rb:

use_helper Nanoc::Helpers::Rendering

To render a partial, call #render with the identifier or a glob as an argument:

<%= render '/head.*' %>

For details, see the documentation for the Rendering helper.