Command-line interface

Interacting with Nanoc happens through a command-line tool named nanoc. This tool has sub-commands, which you can invoke like this:

% nanoc command

Here, command is the name of the command you’re invoking.

Getting help

To get help on a command, invoke the help command with the command you’re interested in as the argument. For example, this is the help for the create-site command:

% nanoc help create-site
nanoc create-site [path]

aliases: cs

create a site

    Create a new site at the given path. The site will use the compact
    file system data source by default, but this can be changed by
    using the --datasource command-line option.

options:

   -d --datasource specify the data source for the new site

To get a list of all commands and global options, invoke the help command without arguments:

% nanoc help

A reference of all commands is available in the Command-line interface page, as well as the command line itself.

Bundler integration

When invoking the Nanoc CLI through Bundler (e.g. using bundle exec nanoc), Nanoc will attempt to require all gems in the nanoc group inside the Gemfile. Gems that are defined in this group thus do not have to be required explicitly. This is particularly useful for gems that define filters, or add commands to the CLI.

For example, with the following Gemfile, Nanoc will load the nanoc-live gem automatically:

group 'nanoc' do
  gem 'nanoc-live'
end

Writing commands

Custom commands live inside the commands/ directory in the site directory. Commands are Ruby source files, where the filename corresponds to the command name.

Here is an example command:

usage       'dostuff [options]'
aliases     :ds, :stuff
summary     'does stuff'
description 'This command does a lot of stuff. I really mean a lot.'

flag   :h, :help,  'show help for this command' do |value, cmd|
  puts cmd.help
  exit 0
end
flag   :m, :more,  'do even more stuff'
option :s, :stuff, 'specify stuff to do', :argument => :optional

run do |opts, args, cmd|
  stuff = opts[:stuff] || 'generic stuff'
  puts "Doing #{stuff}!"

  if opts[:more]
    puts 'Doing it even more!'
  end
end

The name of the command is derived from the filename. For example, a command defined in commands/dostuff.rb will have the name dostuff, and it can thus be invoked as nanoc dostuff.

Commands can be nested; for example, the command at commands/foo/bar.rb will be a sub-command of the command at commands/foo.rb, and can be invoked as nanoc foo bar.

For details on how to create commands, see the documentation for Cri, the framework used by Nanoc for generating commands.