Nanoc»Sites

A site managed by Nanoc is a directory with a specific structure. It contains source data, as well as processing instructions that describe how the site should be compiled.

By default, Nanoc uses the filesystem data source, which means that source data is stored inside the content/ directory. Nanoc can read from other sources too, including databases or web APIs. For details, see the Data sources page.

Creating a site

To create a site, use the create-site command. This command takes the site name as an argument. For example:

% nanoc create-site tutorial
    create  nanoc.yaml
    create  Rules
    create  content/index.html
    create  content/stylesheet.css
    create  layouts/default.html
Created a blank Nanoc site at 'tutorial'. Enjoy!

Directory structure

A site has the following files and directories:

nanoc.yaml (or config.yaml on older sites)
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, … will be available during the compilation process. This directory is useful for putting in custom helpers, custom filters, custom data sources, etc.

Configuration

The configuration for a Nanoc site lives in the nanoc.yaml file (or, on older sites, the config.yaml file). The configuration file is a YAML file with several pre-defined configuration keys, but can also contain free-form data. For example:

prune:
  auto_prune: true
  exclude: ['.git']

data_sources:
  - type: filesystem

base_url: http://nanoc.ws

The example above contains configuration for the pruner in the prune section (auto-prune after every compilation, but don’t touch .git), data sources in the data_sources section (read from the filesystem), and a custom configuration option base_url.

See the Configuration page for a reference of all built-in configuration options.

Compiling a site

To compile a site, invoke nanoc on the command line. For example:

% nanoc
Loading site data… done
Compiling site…
      update  [0.05s]  output/doc/sites/index.html

Site compiled in 2.42s.

It is recommended to use Bundler with Nanoc sites. When using Bundler, compiling a site is done by invoking bundle exec nanoc on the command line.

To pass additional options when compiling a site, invoke the nanoc compile, and pass the desired options.

Nanoc will not compile items that are not outdated. If you want to force Nanoc to recompile everything, delete the output directory and re-run the compile command.

You can use guard-nanoc to automatically recompile the site when it changes.

Environments

Nanoc supports defining multiple environments in which sites can be compiled. For example, a devel (development) and a prod (production) environment, where prod performs additional work that is typically not needed for local development, such as minifying HTML and CSS, converting all paths to be relative, and cleaning up typography.

To specify an environment, pass the -e or --env option to the compile command. For example:

% nanoc compile --env=prod

The environment can be used to modify the configuration. If the configuration has an env section, the loaded configuration will also include the configuration options specified in the env sub-section that matches the environment name. For example:

base_url: http://nanoc.dev

environments:
  prod:
    base_url: http://nanoc.ws

In the example above, the value for the base_url configuration option will be "http://nanoc.dev" by default. When the environment is set to prod (using e.g. --env=prod), the value will be "http://nanoc.ws" instead.

The default environment is, as the name suggests, the environment that will be used when no environment is explicitly specified. The example above is thus equivalent to the following:

environments:
  default:
    base_url: http://nanoc.dev
  prod:
    base_url: http://nanoc.ws

The environment can also be used to affect the rules that are executed. For example:

compile '/book/**/*' do
  filter :kramdown
  layout '/default.*'
  filter :rubypants if ENV['NANOC_ENV'] == 'prod'
end

In the example above, the :rubypants filter will only be run if the Nanoc environment is set to prod.