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