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: https://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 environments section, the loaded configuration will also include the configuration options specified in the environments sub-section that matches the environment name. For example:

base_url: http://nanoc.dev
site_name: Nanoc

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

In the example above, the value for the base_url configuration option will be "http://nanoc.dev" in all environments, but "https://nanoc.ws" in the prod environment. The site_name configuration option will be "Nanoc" in all environments.

The default environment is, as the name suggests, the environment that will be used when no environment is explicitly specified. However, non-default environments will not inherit from the default environment. For example:

site_name: Nanoc

environments:
  default:
    base_url: http://nanoc.dev
    site_name: Nanoc (local)
  prod:
    base_url: https://nanoc.ws

In this example, site_name will be "Nanoc" in all environments, except default, where it is "Nanoc (local)" instead.

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.