Nanoc: a Ruby static-site generator that lives in a monorepo of sixteen packages

The tree is the documentation, because the README is one sentence

The entire prose description of nanoc on GitHub is this: Nanoc is a flexible static-site generator written in Ruby. See the Nanoc web site for more information.

That is the whole README body. Below it sit four badges, pointing at the RubyGems version for the `nanoc` gem, its download count, Codecov coverage for `nanoc/nanoc`, and the contributor count. Below those is a list of well over a hundred contributor names, running from Abubakar Ango to zor-el. There is no installation command, no directory layout, no configuration example and no code sample in the file at all.

This is unusual enough to call out plainly rather than treat as a nitpick, because it changes how you evaluate the project. For nearly every other generator the README is where you decide whether the tool fits. For nanoc, judgement has to come from the repository structure and the release notes, which is what the rest of this article does.

One smaller detail worth recording: the homepage field in the repository metadata points at `http://nanoc.denisdefreyne.com` with no TLS, while the README links to the same host over `https`. The documentation site itself is not where the generation logic lives, so treat it as the place to learn concepts and the repository as the place to learn behaviour.

Twelve nanoc-prefixed directories are the real architecture

The top level of the default branch contains sixteen entries, and twelve of them are directories beginning with `nanoc-`: `nanoc-cli`, `nanoc-core`, `nanoc-spec`, `nanoc-checking`, `nanoc-deploying`, `nanoc-external`, `nanoc-live`, `nanoc-org-mode`, `nanoc-tilt`, `nanoc-dart-sass`, `nanoc/` itself, plus `guard-nanoc`. Alongside them sit `common/` and `scripts/`.

This decomposition is the most informative thing in the repository. A generator that keeps compilation in one gem and pushes deployment, live reloading and template integration into siblings is making a deliberate statement about what changes together and what does not. `nanoc-core` holds the compilation logic, `nanoc-cli` the command surface, `nanoc-spec` the shared test helpers, and the rest are optional integrations that a given site may never load.

The naming is also a compatibility signal. Sites written years ago declare `nanoc` and get the umbrella package; the split means the core can move without forcing every integration to move in lockstep, and the individual gems can be versioned independently when an external dependency forces it.

The `nanoc-dart-sass` directory is a good illustration of the pattern. Rather than bundling a Sass implementation and taking on that dependency's release schedule, the integration lives in its own package next to a `nanoc-tilt` package for the Tilt templating layer. Both are thin by design, and both can be replaced independently.

Two of the last three releases are about compiling less

The release history is short in the recorded data but consistent in theme. Version 4.14.6, published on 2025-12-31, lists one enhancement: sped up incremental compilation, referencing issue 1776. Version 4.14.7, published on 2026-03-07, lists three: add default `robots.txt`, sped up incremental compilation, and improved verbose compilation output. Version 4.14.8, published on 2026-08-30, lists one fix: an issue which would not fully propagate outdatedness through dependencies that use the feature-flagged `#where` method, referencing issue 1787.

Read in sequence, that is a project spending its effort on the recompilation path rather than on new features. Two releases in a row touch incremental compilation, and the third is a bug in the dependency invalidation logic that incremental compilation depends on. The `#where` detail is the tell: a filtering method, feature-flagged, whose participation in outdatedness propagation was incomplete. That is the class of defect you only discover once real sites depend on it.

Improved verbose compilation output in the same 4.14.7 release fits the pattern. When the interesting behaviour is what got skipped during a rebuild, the log is part of the feature, not a debugging afterthought. The default `robots.txt` addition is the one user-facing change in the three releases, and it is small by design.

Three RuboCop configs and a bespoke test runner describe the working style

The root contains `.rubocop.yml`, `.rubocop_new.yml` and `.rubocop_todo.yml`. Most Ruby projects keep one. Keeping three means the project tracks lint state in layers: a baseline of accepted violations, a configuration for newer code, and the main config tying them together. That is what a long-lived codebase with a large contributor base tends to grow, and it is a candid admission that style debt is being contained rather than erased.

The other root files complete the picture. There is a `Gemfile` for development dependencies, a `Rakefile` as the task entry point, `CODE_OF_CONDUCT.md`, a `.gitignore`, and `scripts/` for whatever does not fit in a Rake task. `ddenv.yaml` is the more interesting one. It configures ddenv, a tool the author wrote to run test suites in parallel across machines and processes, which is the kind of infrastructure a suite spread across a dozen gems needs in order to stay fast.

`common/` at the root is the shared ground for those gems, which is how twelve packages in one tree avoid twelve copies of the same helpers. This is what the monorepo shape buys: shared code without publishing a thirteenth gem for it.

None of this is visible in the README, which is precisely the argument for reading the tree.

The satellite gems map nanoc's intended audience

Reading the directory names as a group gives you the project's own account of who uses it, and it is broader than the tagline suggests.

`guard-nanoc` is a Guard plugin, so the intended workflow includes a file watcher that recompiles on save rather than a build step you remember to run. `nanoc-live` covers local preview with live reload. `nanoc-deploying` means deployment is treated as a first-class concern rather than an afterthought bolted on by each site. `nanoc-external` suggests a route for data that does not live in the repository. `nanoc-tilt` and `nanoc-org-mode` cover template languages and an Emacs publishing workflow specifically.

Two of those deserve a second look. `nanoc-org-mode` means the project has real users publishing from Emacs, which is a narrow and demanding audience to support for years. `nanoc-tilt` means template handling goes through Tilt rather than a bespoke implementation, so a Tilt template works without nanoc-specific glue.

The repository metadata backs the popularity claim with numbers: 2158 stars, 251 forks, 17 open issues, topics of nanoc, ruby and static-site-generator, and an MIT licence. A fork count a little under an eighth of the star count is high for a generator, and 17 open issues against that many stars is low, both of which point to a settled rather than abandoned project.

One inconsistency sits in the metadata itself and is worth stating as it stands. The GitHub description reads A powerful web publishing system, while the README calls nanoc a flexible static-site generator. Both are accurate descriptions of what the software is, and the first is the one most people searching will see, so neither should be treated as the correction of the other.

Cadence, freshness and what to check before you commit

The repository is not archived, the default branch is `main`, and the last push recorded in the metadata is 2026-09-28. That is eight days before the 2026-10-06 baseline date, so this is an actively maintained project in the plain sense of the word. The newest published tag is 4.14.8 from 2026-08-30, which means the working tree sits about a month ahead of the last downloadable build, the normal state for a project that tags on release rather than on every merge.

The version number is worth reading for what it implies. Fourteen minor increments past 4.0 signals a project that has spent years keeping a stable public interface and pushing changes forward inside it. That is the good news for anyone with an existing nanoc site, since the upgrade story for a 4.x project is normally a version bump rather than a migration.

What you should check before committing to it is concrete. Read the compilation guide on the website to learn the concepts the README never introduces. Use the `Gemfile` and `Rakefile` at the root as the real entry points to development rather than guessing at commands. If incremental compilation correctness matters to you, which it does for any site over a few hundred files, read the 4.14.8 note about `#where` and outdatedness, because that fix touches exactly the path you would be relying on. And treat the contributor list on the README as a genuine signal, since a hundred-plus named contributors is hard to fake and suggests the project has outlived several of its maintainers.

Editorial conclusion

Nanoc is a good fit if you write Ruby, want a generator whose compilation model you can actually reason about, and would rather extend it with your own Ruby code than fight a plugin API. The dependency graph is the reason to trust it: a project this old, with a dozen gems released in lockstep from one tree, only stays coherent because the parts have clean boundaries. What you accept is a project whose public description is a promotional phrase, whose README would not get you running, and whose fastest path to documentation is the separate website. The recent release notes are the most reassuring artifact available, because two consecutive releases are about making recompilation skip more work and the newest is a correctness fix in dependency outdatedness, which is the kind of bug you only find in a system that caches aggressively. Pin a version, read the guide on the website rather than the README, and use the Rakefile and Gemfile in the root as the actual entry points to the development setup.

Frequently asked questions

Official sources

1. License: MIT
2. nanoc/nanoc on GitHub
3. Project website
4. README
5. Releases