1. Computing
Send to a Friend via Email

Spotlight on Gems: nanoc

By

Which Ruby web framework you use is heavily dependent on the requirements of your site. Large database-driven sites will probably want to use something like Rails or Merb. The advantages here for large scale and feature-heavy sites are undeniable. Smaller sites might want to use something like Sinatra where complexity is at a minimum. But there's an even smaller-class site: the static HTML page.

If your site is static HTML pages, what does Ruby have to do with anything? After all, you just write the HTML out and upload it to the server, right? This is the "boring way" of doing static HTML. Enter nanoc, a framework for generating static HTML pages in Ruby. If you've ever programmed static HTML pages before, you'll see immediately why a framework is beneficial. Because things aren't dynamically generated on the server, elements that appear in multiple pages (the navigation menu, for example) have to be written multiple times. The nanoc framework solves this problem, and that's just scratching the surface.

Another really great advantage to using nanoc that should be mentioned upfront is it shields you from HTML where HTML is not important. You can write your code in Markdown (a simple markup language much less cumbersome than HTML), and have nanoc render it to HTML.

Installing nanoc

The nanoc framework is a simple gem with no native dependencies. Install it as any other gem. Be aware that there are (at least) 2 gems for nanoc, one called nanoc and one called nanoc3. The nanoc3 gem installs the 3.x branch, and nanoc installs the 2.x branch.


$ sudo gem install nanoc3

Generating Projects

The nanoc framework can generate projects for you, much like Rails. To do this, run the command nanoc3 create_site my_site_name. This will create a directory called my_site_name with all code, pages and configuration files to generate an HTML site.

These are the major points of interest inside this directory.

  • content - A directory containing the uncompiled sources the HTML code is generated from.
  • layouts - The layouts, including the default layout used on all pages.
  • config.yaml - Global configuration variables.
  • lib - Helpers and other related code goes in here.
  • output - The generated HTML pages will go in here.

Compiling and Using the Autocompiler

Once you've created pages and edited them, it's time to compile them to HTML. To do this, run the command nanoc3 compile from your project directory. If everything goes well, you'll get the HTML documents output in the content directory. You can then copy these onto your web server using FTP, SSH or any other method.

One really useful feature is the autocompiler. The autocompiler will start a Rack server (with Webrick or Mongrel) to serve the files in the content directory. However, the really useful part is that whenever a request is made to the server, it will recompile the project so your changes show up instantly. To start up the autocompiler server, run the command nanoc3 aco and point your web browser to http://localhost:3000/.

More Information

For more information about nanoc, refer to the nanoc homepage. Of particular interest is the tutorial and manual.

  1. About.com
  2. Computing
  3. Ruby
  4. Gems
  5. Spotlight on Gems: nanoc

©2014 About.com. All rights reserved.