Checking correctness of Nanoc sites

Nanoc comes with tooling for ensuring that your site has no errors, such as broken links, stale files in the output directory, and mixed HTTP/HTTPS content. Such checks can be run:

manually, using the check command
automatically, as part of the deployment process (invoked by the deploy command)

Running checks manually

To run a single check, run the check with the name of the check as an argument:

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

Running checks before deploying

Specify the list of checks to run before deploying in the enabled_checks array within the checking section of the configuration file (nanoc.yaml):

checking:
  enabled_checks:
    - internal_links
    - stale

The example above prevents the Nanoc site from being deployed if there are broken internal links or stale files in the output directory.

Deploy-time checks can also be configured in a file named Checks in the site directory. To configure a check to be run before deploying, call #deploy_check with name of the check:

deploy_check :internal_links
deploy_check :stale

Use of the Checks file is discouraged, however.

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!
  output/doc/guides/unit-testing-nanoc-sites/index.html:
    [ ERROR ] internal_links - broken reference to ../../api/Nanoc/Site.html
Issues found, deploy aborted.
%

You can also run nanoc check to run all enabled checks.

Defining custom checks

To define a custom check, use Nanoc::Check.define, somewhere in the lib/ directory:

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

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.

Custom checks can also be defined in a file named Checks in the site directory. To define a check in this way, call the #check method with the name of the check, and a block:

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

Use of the Checks file is discouraged, however.

Available checks

Nanoc comes with the following checks:

css: verifies that the CSS is valid
html: verifies that the HTML is valid
external_links
elinks: verifies that external links are correct
internal_links
ilinks: verifies that internal links are correct
stale: verifies whether no non-Nanoc items are in the output directory
mixed_content: verifies that no content is included or linked to from a potentially insecure source