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

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.

Live recompilation

Nanoc supports live recompilation, which will recompile the site whenever any changes are made. To set up live recompilation, add the nanoc-live gem inside the nanoc group in your Gemfile:

group 'nanoc' do
  gem 'nanoc-live'
end

If your Gemfile contains the line gem 'guard-nanoc', remove it. The guard-nanoc gem provides similar (but older) functionality to nanoc-live.

Now you can use the nanoc live command, which automatically recompiles and runs a web server that reloads your browser when changes are made.

% nanoc live
View the site at http://127.0.0.1:3000/
[2021-02-20 09:38:52] INFO  WEBrick 1.7.0
[2021-02-20 09:38:52] INFO  ruby 3.0.0 (2020-12-25) [x86_64-darwin20]
[2021-02-20 09:38:52] INFO  WEBrick::HTTPServer#start: pid=78056 port=3000
Compiling site…
Site compiled in 0.69s.

Listening for site changes…

Visit the URL that nanoc live prints (in this case, http://127.0.0.1:3000/), make some changes to your site content, and you’ll see your changes reflected in the browser just after you save.

You can also use the compile --watch command, which will recompile without running a web server.

On Ruby 3.0 and later, you might get the following error:

LoadError: Couldn't find handler for: puma, thin, falcon, webrick.

To fix this, add the webrick gem to your Gemfile:

gem 'webrick'

Focused compilation

The compile and live commands have a --focus option, which tells Nanoc to only recompile items matching the given identifier. This is helpful for very large sites, where doing a full recompile can be time-consuming.

For example, here I tell Nanoc to only recompile my stylesheets and the homepage:

% nanoc live --focus="/style/**/*" --focus="/index.*"
[snip]
Reloading site… done
Compiling site…
      delete  output/style/2021q4_twknk-phxkn-wr7xw.css
      create  [0.70s]  output/style/2021q4_rwvlp-ktclz-cw9xc.css
      update  [0.00s]  output/index.html
Site compiled in 2.75s.
CAUTION: A --focus option is specified. Not the entire site has been compiled.
Re-run without --focus to compile the entire site.

Before deploying, be sure to run the compile command without the --focus option. Otherwise, it is likely that the compiled site is not fully consistent, or even broken entirely.

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

In the example above, the value for the base_url configuration option will be "http://nanoc.dev" in all environments, but "https://nanoc.app" 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.app

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.