Install Nanoc using RubyGems:
% gem install nanoc
For detailed installation instructions, read on.
On Ruby 3.0 and later, you might get this error error when running nanoc view:
LoadError: Couldn't find handler for: puma, thin, falcon, webrick.
This happens because Ruby 3.0 and later does not come with WEBrick by default, while older Ruby versions (2.x) do.
To resolve this, add WEBrick to your Gemfile: bundle add webrick.
Nanoc guarantees backwards compatibility within the same major version, starting from Nanoc 3.0 (released in 2009). This means that it is possible to upgrade from any 4.x to any newer 4.x version without extra work.
We recommend specifying the version of Nanoc using the
~> operator in the Gemfile, and specifying only the major and minor version. For example:
gem 'nanoc', '~> 4.12'
This version constraint tells Bundler to use at least Nanoc version 4.12, but never upgrade beyond version 4. This way, running bundle update nanoc will upgrade Nanoc to the last compatible version.
We recommend updating Nanoc regularly. New versions not only come with new features, but also with bug fixes and performance improvements that continuously make Nanoc more enjoyable to use.
Language version: Ruby 2.5 or higher. Nanoc might run fine on older versions, but there are no guarantees that it will.
Implementation: CRuby. Alternative Ruby interpreters, such as JRuby and Rubinius, might be able to run Nanoc, but there are no guarantees that they will be able to do so properly.
Operating system: macOS, Linux. Nanoc runs mostly fine on Windows, with some limitations. Windows is not officially supported at this point, but that is being worked on.
Nanoc requires Ruby to run. Nanoc supports the official Ruby interpreter from version 2.5 up.
Ruby may already be installed on your system. To check, open a terminal window and type ruby --version. If you get “command not found”, Ruby is not yet installed. Otherwise, you will see which version of Ruby you have:
% ruby --version ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux] %
To install Ruby, follow the installation instructions on the Ruby website.
All dependencies are now taken care of, and installing Nanoc should now be easy:
% gem install nanoc
To make sure that Nanoc was installed correctly, run nanoc --version. It should print the version number along with some other information, like this:
% nanoc --version Nanoc 4.12.2 © 2007–2021 Denis Defreyne. Running ruby 2.6.3 (2019-04-16) on x86_64-linux with RubyGems 3.0.8. %
If you get a “command not found” error when trying to run nanoc, you might have to adjust your
$PATH to include the path to the directory where RubyGems installs executables.
The current version of Nanoc is 4.12.2, released on May 28th, 2021. You can find the release notes for this version as well as release notes for older versions on the Release notes page.
If you’re on Windows and are using the Windows console, it’s probably a good idea to install the win32console gem using gem install win32console to allow Nanoc to use pretty colors when writing stuff to the terminal.
Installing from git
You can also install Nanoc from the repository if you want to take advantage of the latest features and improvements in Nanoc. Be warned that the versions from the repository may be unstable, so it is recommended to install Nanoc from RubyGems if you want to stay safe. You can install Nanoc from the git repository like this:
~% git clone git://github.com/nanoc/nanoc.git ~% cd nanoc ~/nanoc% gem build nanoc.gemspec ~/nanoc% gem install nanoc-*.gem