Create a powerful static website with nanoc
Forget Drupal, WordPress and Rails: nanoc compiles your documents into a static website
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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’.
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.
The ‘nanoc help’ command shows you which commands nanoc knows and ‘nanoc help
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.