What’s new?

This page summarizes new features in minor releases. For a detailed list of all changes in all versions, see the Release notes page.

Nanoc 4.11

In Nanoc 4.11, the Sass filter supports generating inline source maps. To do so, pass sourcemap_path: :inline:

compile '/assets/*.scss'
  filter :sass, syntax: :sass, sourcemap_path: :inline
  write ext: 'css'

Secondly, the Breadcrumbs helper’s #breadcrumbs_trail function can now deal with ambiguity. There are cases where one item has more than one potential parent item, and the new :tiebreaker option can now be used to deal with that. See the Dealing with ambiguity section on the Helpers page for details.

Nanoc 4.10

Nanoc 4.10 comes with an upgraded Sass filter. It comes with a new nanoc() Sass function, which allows pulling in Nanoc site data into stylesheets:

.title {
  content: nanoc('@config[:title]');

The Sass filter also comes with a matching :sass_sourcemap filter, which generates Sass source maps. See the Using Sass source maps section on the Using common filters page for details.

Nanoc 4.9

The list of enabled checks can now be specified in the configuration file, rather than the Checks file. For example:

# in the Checks file
deploy_check :internal_links
deploy_check :stale
# in nanoc.yaml
    - internal_links
    - stale

Additionally, custom check can now be defined using Nanoc::Check.define, somewhere in the lib/ directory:

# in the Checks file
check :no_unprocessed_erb do
  @output_filenames.each do |filename|
    if filename =~ /html$/ && File.read(filename).match(/<%/)
      add_issue("unprocessed erb detected", subject: filename)
# somewhere in lib/
Nanoc::Check.define(:no_unprocessed_erb) do
  @output_filenames.each do |filename|
    if filename =~ /html$/ && File.read(filename).match(/<%/)
      add_issue("unprocessed erb detected", subject: filename)

Lastly, invoking the check command with no options will now run all enabled checks (either enabled using deploy_check in the Checks file, or listed under enabled_checks in the configuration file).

Use of the Checks file is discouraged from now on, though the functionality will not be removed before Nanoc 5.0 (and there are no plans to start working on Nanoc 5.0 at this point in time).

Identifiers now also have a #match? method, which returns true if the identifier matches the given pattern, false otherwise.

Nanoc 4.8

Nanoc 4.8 adds an asciidoctor filter, for invoking Asciidoctor, a Ruby implementation of AsciiDoc:

compile '/**/*.adoc' do
  filter :asciidoctor
  layout '/page.*'
  write ext: 'html'

Previously, the asciidoctor was available through the nanoc-asciidoctor gem, which is now obsolete.

Nanoc 4.7

Nanoc 4.7 adds a shortcut for writing an item with a specific extension, while retaining the base name:

compile '/**/*.md' do
  filter :kramdown
  write ext: 'html'

Previously, you’d have to use the rather verbose write item.identifier.without_exts + '.html'.

Nanoc 4.7 also adds the :erubi filter, which calls Erubi, an ERB template engine for Ruby.

Nanoc 4.6

Nanoc 4.6 adds #snapshot? to item representations. It returns true if the given representations has a snapshot with the given name, false otherwise. For example:

<% if @rep.snapshot?(:latex) %>
  <link rel=stylesheet href=latex.css>
<% end %>

The #content_for function, part of the capturing helper (see the Capturing section on the Helpers page for details), can now be used to set captured content directly:

content_for(:head, 'stuff')

Previously, setting captured content manually was only possible by appending to _erbout:

content_for(:head) { _erbout << 'stuff' }

When passing a string to the #content_for function, parameters are passed before the string argument:

content_for(:head, existing: :append, 'stuff')

Lastly, items and layouts now have #raw_content= during preprocessing, to allow changing the raw content of items and layouts.

Nanoc 4.5

Nanoc 4.5 bundles the Git deployer, which used to be in the nanoc-git repository. The nanoc-git gem can be removed from the Gemfile. For details, see the With GitHub Pages or Bitbucket section on the Deploying Nanoc sites page.

Nanoc 4.4

Nanoc 4.4 adds support for environments. The compile command now takes an --env option, e.g. nanoc compile --env=prod, which sets the NANOC_ENV environment variable to the given value, and also changes the way the configuration is read.

The configuration can now contain an environments section, like this:

base_url: http://nanoc.dev

    base_url: http://nanoc.ws
    base_url: http://staging.nanoc.ws

When an environment is specified on the command line, the data for the environment with the given name will be merged into the top level of the configuration. For example, with --env=prod, the configuration effectively becomes as follows:

base_url: http://nanoc.ws

For details about environments, see the Environments section on the Sites page.

Nanoc 4.3

Nanoc 4.3 adds Nanoc::Filter.define, which makes defining filters a little less verbose:

Nanoc::Filter.define(:censor) do |content, params|
  content.gsub('Nanoc sucks', 'Nanoc rocks')

See the Writing filters section on the Filters page for details.

Additionally, Nanoc will automatically require all gems defined in the nanoc group in the Gemfile. This is particularly useful for the guard-nanoc gem, which, when added to the nanoc group in the Gemfile, will add a new live command to nanoc. This nanoc live command simultaneously recompiles the site on changes, and runs a web server. See the guard-nanoc repository for details.

Nanoc 4.2 and older

Release notes are pending. For the time being, see the Release notes page.