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

Nanoc 4.13 adds a --focus option to the compile and live commands, 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. With --focus, you can tighten the feedback loop.

For example, here I tell Nanoc to only recompile my stylesheets, which are located in the content/assets/style directory:

% nanoc live --focus="/assets/style/**/*""
[snip]
Reloading site… done
Compiling site…
      delete  output/assets/style/2021q4_twknk-phxkn-wr7xw.css
      create  [0.70s]  output/assets/style/2021q4_rwvlp-ktclz-cw9xc.css
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.

The --focus option can be specified more than once, too:

% nanoc live --focus="/assets/style/**/*" --focus="/index.*"
[snip]
Reloading site… done
Compiling site…
      delete  output/assets/style/2021q4_twknk-phxkn-wr7xw.css
      create  [0.70s]  output/assets/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.

Nanoc 4.12

Nanoc 4.12 comes with some minor changes that will make your Nanoc workflow faster: improved live recompilation, and caching of compiled binary content.

Better live recompilation

The compile command now has a --watch (-W) flag, which will automatically recompile when changes are made.

To use this, install the newly-released nanoc-live by adding it 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.

In addition to compile --watch, you can also use the new 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.

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'

Binary content caching

While previous versions of Nanoc already kept a cache of compiled textual content (such as compiled Markdown files), this wasn’t yet the case for binary content (such as images). Nanoc 4.12 now caches compiled binary content as well, which will provide a speedup for asset-heavy web sites.

To minimize disk space usage for this cache of compiled binary content, add clonefile to your Gemfile:

gem 'clonefile'

This will enable copy-on-write (COW) support on modern filesystems such as APFS (but not HFS+).

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'
end

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
checking:
  enabled_checks:
    - 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)
    end
  end
end

# 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)
    end
  end
end

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'
end

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'
end

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

environments:
  prod:
    base_url: https://nanoc.app
  staging:
    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: https://nanoc.app

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')
end

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.