Create a powerful static website with nanoc

Forget Drupal, WordPress and Rails: nanoc compiles your documents into a static website

Web development

Step 10

YAML files

Depending on your editor, having YAML attributes at the top of every source HTML file may break syntax highlighting. If you don’t like this, you can always put the attributes in a YAML file with the same name as its HTML page but with the .yaml extension.

Step 11

Additional pages

Until now you have just changed the example page, but adding pages is easy: just run the ‘nanoc create_item pagename’ command. For instance, create an about or a contact page. Then edit the files in the content directory, add some content and change the title attribute.

Step 12

Change the rules

The file Rules contains some rules that define how nanoc compiles your website. Compilation rules determine how your content is processed, routing rules determine the path where the compiled files are written to, and layouting rules determine how a given layout is filtered.

Step 13

Layouting rules

By default, the layouting rule is ‘layout ‘*’,:erb’, which means that any layout will use the :erb filter that runs embedded Ruby and shows the result inline. If you want to create an additional layout file layouts/html5.html that outputs HTML5 content, add ‘layout ‘/html5/’, :haml, :format => :html5’ before the default layouting rule.

Step 14

Routing rules

By default, the result of the source file about.html will be written to about/index.html, so you access it in your web browser on http:// localhost:3000/about/. However, if you don’t like the extra directory for each file, duplicate the routing rule ‘route “*” do’, change the ‘*’ to ‘/’ in the first instance and change ‘item.identifier + “index.html” ’ to ‘item.identifier.chop + “.html” ’ in the second instance.

Step 15

Compilation rules

The compilation rules determine how nanoc processes your original source files. The default compilation rule excludes binary files (such as images) and stylesheets from further processing, but for the other files it calls the embedded Ruby filter (erb) and it uses the default layout. If you prefer to write your source files in Markdown instead of an HTML fragment, change the ‘filter :erb’ to ‘filter :kramdown’. You can also run multiple filters and layouts sequentially. For instance, you can add ‘filter :rubypants’ at the end of the compilation rule to translate plain punctuation into the right HTML entities.

Step 16

Other filters

We’ve seen the erb, kramdown, haml and rubypants filters, but nanoc also has filters to support AsciiDoc or Textile syntax, various Markdown dialects for your content, the Slim template language, CoffeeScript, the UglifyJS compressor for JavaScript, the LESS or Cass extensions of CSS, the Rainpress compressor for CSS, an XSLT processor and so on.

Web development
Other filters

Step 17

Syntax colouring

One interesting filter is ColorizeSyntax. You just give your code snippets the HTML class starting with ‘language-’ and followed by the code language, for instance ‘language-ruby’. Then you define the :colorize_syntax filter in the Rules file, optionally with parameters defining which colorizer to use for which language.

Step 18


Nanoc also comes with some handy helper functions, such as for creating a blog, creating a breadcrumb trail from a page to its parent, working with HTML escapes, managing tags added to pages, building an XML sitemap, and so on. A helper can be used in erb code.

Step 19


One interesting helper is LinkTo. You can use ‘link_to(“About”, “/about/”)’ to create a link to the page with identifier ‘about’. Even more: the code ‘link_to_unless_current(“About”, “/about/”)’ creates a link to this page except when the linked page is the current page, which is interesting in a menu.

Step 20

Writing helpers

If nanoc’s default functionality is not enough for your purpose (but first do look at the online API documentation), you can extend it with custom helpers. Create an .rb file with a Ruby module with your method in the lib/helpers/ directory and include the module in the file lib/helpers_.rb, after which you can call the method in erb.

Step 21

Validate your site

Before you deploy your website, you should first validate if all output is valid. Fortunately, nanoc has some commands to check this. First, install the Ruby Gems w3c_validators and nokogiri, after which you can use the commands ‘nanoc validate-html’, ‘nanoc validate-css’ and ‘nanoc validate-links’.

Step 22

Deploy your site

Now it’s time to deploy your website. Because it’s completely static, this is as easy as copying the contents of the directory output to your web host. If your web host supports rsync, define a deploy attribute in config.yaml which defines the target destination. After this, the command ‘nanoc deploy –target targetname’ deploys your website.

Step 23

Nanoc help

The ‘nanoc help’ command shows you which commands nanoc knows and ‘nanoc help ’ even shows extensive help about the specific command, including all possible options. For troubleshooting, the –verbose and (for hardcore programmers) –debug options are very handy.

Step 24

Nanoc API

If you want to delve even deeper into the inner workings of nanoc, for instance because you want to write custom filters or helpers, consult the extensive API documentation. But even if you just want to use some of the more advanced functionality of nanoc, this is the place to look.

Web development
Nanoc API