Nanoc and Static Web Sites

A few days ago we looked at Webby for generating static web sites. I had a couple of issues with it, including the fact that it didn't work with ruby 1.9.2 and it hasn't been updated for a couple of years now. Someone on the Ramaze email list suggested that I should take a look at nanoc too. It seems to have many of the same features as webby, but is actively maintained and runs on ruby 1.9.2. So let's take a look at getting it up, running, and generating a site. First, we'll need to add a few gems ...


gem install nanoc
gem install kramdown
gem install adsf


Here we're installing nanoc itself, kramdown, which is a Markdown converter, and adsf, which is used as a web server for showing the site.

With that out of the way, let's go ahead and create a new site ...

nanoc create_site my_site

This should create a new site in the directory my_site that has a few different files and directories. Go ahead and cd into the directory and then

nanoc compile

which should "compile" the site. In this case, compile will create an output directory where the resulting HTML files will reside. OK, now we can start a web server with

nanoc view

and then point our browser at http://localhost:3000. At this point you should see the default site for nanoc. For viewing, you could also use

nanoc autocompile

which will also compile a file when changes are made to the site automatically. For "real" work, this is probably the option to use.

OK, let's take a look at the content directory. This is where nanoc will keep the files that will get compiled and moved to the output directory. Go ahead and open up content/index.html in your favorite text editor and make a few changes. Go back to the browser, reload, and you should see your changes there. Now, take a look at layout/default.html. If you make a change in there, say adding an h1 tag before the h2 Documentation tag, it will appear in all the pages that are generated.

Finally, we're going to need to add new pages if this is going to be useful. Try this ...

nanoc create_item test

This will create a test.htnml in the content directory and when it gets compiled, you should be able to go to http://localhost:3000/test/ (don't forget the final "/") and see the page. A couple of things to note here. In the output directory, this will be output/test/index.html.

This should be enough to get you started. Definitely check out the nanoc site for more information. I'm going to use this to generate a personal site, so I'll let you know how it goes and what good/bad things I see.

Let me know if you have questions or comments.