Blog

nanoc 3.1 released (April 3rd, 2010)

nanoc 3.1 is out now. This release introduces quite a few useful features, including API improvements and support for binary assets. Check the full release notes for details. Here’s how to install nanoc 3.1:

% gem install nanoc

nanoc 3.1 is backwards compatible with nanoc 3.0.x. All sites built with nanoc 3.0.x should compile without issues on nanoc 3.1.

The biggest new feature is support for binary assets. Files such as images, audio files and movies can now easily be managed by nanoc. They behave just like textual items; you can drop them in the content/ directory and they can have metadata as well. Filtering binary items is easy as well; here’s an example of a :rotate filter that uses the sips command, built into Mac OS X, for rotating images:

class RotateFilter < Nanoc3::Filter

  identifier :rotate
  type       :binary

  def run(filename, params={})
    system(
      'sips',
      '--rotate', params[:angle].to_s,
      '--out',    output_filename,
      filename
    )
  end

end

This filter can now be invoked like any other filter. For example, suppose you have a content/images/tree.jpg image, you can write the following rules for creating a rotated version:

compile '/images/tree/' do
  filter :rotate, :angle => 5.0
end

route '/images/tree/' do
  '/assets/images/tree-rotated.jpg'
end

Filters can also convert textual content to binary content and vice versa. For example, here’s a text-to-speech filter that uses Mac OS X’s say command:

class SynthesiseAudio < Nanoc3::Filter

  identifier :synthesise_audio
  type       :text => :binary

  def run(content, params={})
    system('say', content, '-o', output_filename)
  end

end

Check out the writing filters section of the manual for details.

Binary items behave like textual items, with the exception that you cannot request their compiled content. Binary assets can have metadata too, just like normal items. This can be quite useful in some cases. For example, if you have a screenshot with the following metadata:

alt: "A screenshot of my desktop."

… then you can output the path to that screenshot as well as its “alt” attribute like this (assuming that the screenshot object points to that very screenshot item):

<img src="<%= screenshot.path %>" alt="<%= screenshot[:alt] %>">

… and you’ll get this output:

<img src="/assets/images/screenshot.png" alt="A screenshot of my desktop.">

The site configuration has a text_extensions array containing a list of extensions; when the site is loaded, files with an extension in that list will be considered as being textual instead of binary. If you use textual items with custom extensions, be sure to add their extension to the text_extensions list. The default list is defined like this:

text_extensions: [ 'css', 'erb', 'haml', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'php', 'rb', 'sass', 'txt' ]

Accessing compiled content and paths of compiled items is easier in 3.1. To get the compiled content of an item, use item.compiled_content; this will get the compiled content at the :pre snapshot of the default representation. You can customize this behaviour with parameters; for example, to get the content at the :clean snapshot of the :xml representation, use item.compiled_content(:rep => :xml, :snapshot => :clean). Getting paths is easier too: item.path—and this method takes parameters to, so you can say item.path(:rep => :xml) to get the path of the :xml representation.

The old way:

item.reps.find { |r| r.name == :default }.path
item.reps.find { |r| r.name == :default }.content_at_snapshot(:pre)
item.reps.find { |r| r.name == :pretty }.content_at_snapshot(:pre)
item.reps.find { |r| r.name == :default }.content_at_snapshot(:clean)

The new way:

item.path
item.compiled_content
item.compiled_content(:rep => :pretty)
item.compiled_content(:snapshot => :clean)

So, install nanoc 3.1 and give it a try. If you have questions or are experiencing issues, let me know on the nanoc mailinglist or on the nanoc IRC channel. Enjoy!