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!
A site has the following files and directories:
- nanoc.yaml (or config.yaml on older sites)
- contains the site configuration
- contains compilation, routing, and layouting rules
- contains the uncompiled items
- contains the layouts
- contains custom site-specific code (filters, helpers, …)
- contains the compiled site
- contains data used for speeding up compilation (can be safely emptied)
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.
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
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.
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
--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.
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