Testing Nanoc sites

The check command is used to verify that a compiled site meets the requirements.

A check can be run using nanoc check check-name. For instance, the following will run the internal links check (internal_links or ilinks):

% nanoc check ilinks
Loading site data… done
  Running internal_links check…   ok

Available checks

Nanoc comes with the following checks:

verifies that the CSS is valid
verifies that the HTML is valid
verifies that external links are correct
verifies that internal links are correct
verifies whether no non-Nanoc items are in the output directory
verifies that no content is included or linked to from a potentially insecure source

Deployment-time checks

A file named Checks at the root of a Nanoc site defines which checks should be run before a nanoc deploy.

Here is an example Checks file that ensures that a Nanoc site does not get deployed if there are broken internal links or stale files in the output directory:

deploy_check :internal_links
deploy_check :stale

Here’s what a nanoc deploy looks like when all checks pass:

% nanoc deploy
Loading site data… done
Running issue checks…
  Running internal_links check…   ok
  Running stale check…            ok
No issues found. Deploying!

Here’s what a nanoc deploy looks like when some checks fail:

% nanoc deploy
Loading site data… done
Running issue checks…
  Running check internal_links…   error
  Running check stale…            ok
Issues found!
    [ ERROR ] internal_links - broken reference to ../../api/Nanoc/Site.html
Issues found, deploy aborted.

To run the checks marked for deployment without deploying, use nanoc check --deploy.

Custom checks

The Checks file is also used to define custom checks. Here is an example check that verifies that no compiled files contain <% and therefore likely include unprocessed ERB instructions:

check :no_unprocessed_erb do
  @output_filenames.each do |fn|
    if fn =~ /html$/ && File.read(fn).match(/<%/)
      add_issue("erb detected", :subject => fn)

In a custom check, you can use #add_issue. The first argument is the description of the problem, and the :subject option defines the location of the problem (usually a filename).

In a custom check, the variables @config, @items, and @layouts are available, in addition to @output_filenames, which is the collection of filenames in the output directory that correspond to an item in the site. For details, see the Variables page.