nanoc-cachebuster 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--format documentation --color -r spec/spec_helper.rb

data/HISTORY.md

@@ -0,0 +1,5 @@
+# 0.0.1
+
+* No more re-calculation of fingerprints, just use the routed filename.
+* Refactored into separate strategies.
+* First, direct extraction.

data/LICENSE

@@ -0,0 +1 @@
+

data/README.md

@@ -0,0 +1,81 @@
+A simple Ruby gem that enhances Nanoc with cache-busting capabilities.
+
+Description
+===========
+
+Your website should use far-future expires headers on static assets, to make
+the best use of client-side caching. But when a file is cached, updates won't
+get picked up. Cache busting is the practice of making the filename of a
+cached asset unique to its content, so it can be cached without having to
+worry about future changes.
+
+This gem adds a filter and some helper methods to Nanoc, the static site
+generator, to simplify the process of making asset filenames unique. It helps
+you output fingerprinted filenames, and refer to them from your source files.
+
+More information
+----------------
+
+Find out more about Nanoc by Denis Defreyne at http://nanoc.stoneship.org.
+
+Installation
+============
+
+As an extension to Nanoc, you need to have that installed and working before
+you can add this gem. When your Nanoc project is up and running, simply
+install this gem:
+
+    $ gem install nanoc-cachebuster
+
+Then load it via your project Gemfile or in `./lib/default.rb`:
+
+    require 'nanoc3/cachebuster'
+
+Usage
+=====
+
+This gem provides a Nanoc filter you can use to rewrite references to static
+assets in your source files. These will be picked up automatically.
+
+So, when you include a stylesheet:
+
+    <link rel="stylesheet" href="styles.css">
+
+This filter will change that on compilation to:
+
+    <link rel="stylesheet" href="styles-cb7a4bb98ef.css">
+
+The adjusted filename changes every time the file itself changes, so you don't
+want to code that by hand in your Rules file. Instead, use the helper methods
+provided. First, include the helpers in your ./lib/default.rb:
+
+    include Nanoc3::Helpers::CacheBusting
+
+Then you can use `#should_cachebust?` and `#cachebusting_hash` in your routing
+rules to determine whether an item needs cachebusting, and get the fingerprint
+for it. So you can do something like:
+
+    route 'styles' do
+      fp = cachebust?(item) ? fingerprint(item[:filename]) : ''
+      item.identifier.chop + fp + '.' + item[:extension]
+    end
+
+Development
+===========
+
+Changes
+-------
+
+See HISTORY.md for the full changelog.
+
+Dependencies
+------------
+
+nanoc-cachebuster obviously depends on Nanoc, but has no further dependencies.
+To test it you will need Rspec.
+
+Credits
+=======
+
+* **Author**: Arjan van der Gaag <arjan@arjanvandergaag.nl>
+* **License**: MIT License (same as Ruby, see LICENSE)

data/Rakefile

@@ -0,0 +1,94 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'nanoc3/cachebuster/version'
+
+task :build do
+  sh 'gem build nanoc-cachebuster.gemspec'
+end
+
+desc 'Install the gem locally'
+task :install => :build do
+  sh "gem install nanoc-cachebuster-#{Nanoc3::Cachebuster::VERSION}.gem"
+end
+
+task :tag do
+  sh "git tag -a #{Nanoc3::Cachebuster::VERSION}"
+end
+
+task :push do
+  sh 'git push origin master'
+  sh 'git push --tags'
+end
+
+task :log do
+  changes = `git log --oneline $(git describe --abbrev=0 2>/dev/null)..HEAD`
+  abort 'Nothing to do' if changes.empty?
+
+  changes.gsub!(/^\w+/, '*')
+  path = File.expand_path('../HISTORY.md', __FILE__)
+
+  original_content = File.read(path)
+  addition = "# #{Nanoc3::Cachebuster::VERSION}\n\n#{changes}"
+  puts addition
+
+  File.open(path, 'w') do |f|
+    f.write "#{addition}\n#{original_content}"
+  end
+end
+
+desc 'Tag the code, push upstream, build and push the gem'
+task :release => [:install, :push] do
+  sh "gem push nanoc-cachebuster-#{Nanoc3::Cachebuster::VERSION}"
+end
+
+desc 'Print current version number'
+task :version do
+  puts Nanoc3::Cachebuster::VERSION
+end
+
+class Version
+  def initialize(version_string)
+    @major, @minor, @patch = version_string.split('.').map { |s| s.to_i }
+  end
+
+  def bump(part)
+    case part
+    when :major then @major, @minor, @patch = @major + 1, 0, 0
+    when :minor then @minor, @patch = @minor + 1, 0
+    when :patch then @patch += 1
+    end
+    self
+  end
+
+  def to_s
+    [@major, @minor, @patch].join('.')
+  end
+
+  def write
+    file = File.expand_path('../lib/nanoc3/cachebuster/version.rb', __FILE__)
+    original_contents = File.read(file)
+    File.open(file, 'w') do |f|
+      f.write original_contents.gsub(/VERSION = ('|")\d+\.\d+\.\d+\1/, "VERSION = '#{to_s}'")
+    end
+    puts to_s
+    to_s
+  end
+end
+
+namespace :version do
+  namespace :bump do
+    desc 'Bump a major version'
+    task :major do
+      Version.new(Nanoc3::Cachebuster::VERSION).bump(:major).write
+    end
+
+    desc 'Bump a minor version'
+    task :minor do
+      Version.new(Nanoc3::Cachebuster::VERSION).bump(:minor).write
+    end
+
+    desc 'Bump a patch version'
+    task :patch do
+      Version.new(Nanoc3::Cachebuster::VERSION).bump(:patch).write
+    end
+  end
+end

data/lib/nanoc3/cachebuster/strategy.rb

@@ -0,0 +1,148 @@
+module Nanoc3
+  module Cachebuster
+    # The Strategy is a way to deal with an input file. The Cache busting filter
+    # will use a strategy to process all references. You may want to use different
+    # strategies for different file types.
+    #
+    # @abstract
+    class Strategy
+
+      @subclasses = {}
+
+      def self.inherited(subclass)
+        @subclasses[subclass.to_s.split('::').last.downcase.to_sym] = subclass
+      end
+
+      def self.for(kind, site, item)
+        klass = @subclasses[kind]
+        raise Nanoc3::Cachebuster::NoSuchStrategy.new "No strategy found for #{kind}" unless klass
+        klass.new(site, item)
+      end
+
+      # The current site. We need a reference to that in a strategy,
+      # so we can browse through all its items.
+      #
+      # This might very well have been just the site#items array, but for
+      # future portability we might as well carry the entire site object
+      # over.
+      #
+      # @return <Nanoc3::Site>
+      attr_reader :site
+
+      # The Nanoc item we are currently filtering.
+      #
+      # @return <Nanoc3::Item>
+      attr_reader :current_item
+
+      def initialize(site, current_item)
+        @site, @current_item = site, current_item
+      end
+
+      # Abstract method that subclasses (actual strategies) should
+      # implement.
+      #
+      # @abstract
+      def apply
+        raise Exception, 'Must be implemented in a subclass'
+      end
+
+    protected
+
+      # Try to find the source path of a referenced file.
+      #
+      # This will use Nanoc's routing rules to try and find an item whose output
+      # path matches the path given, which is a source reference. It returns
+      # the path to the content file if a match is found.
+      #
+      # As an example, when we use the input file "assets/styles.scss" for our
+      # stylesheet, then we refer to that file in our HTML as "assets/styles.css".
+      # Given the output filename, this method will return the input filename.
+      #
+      # @raises NoSuchSourceFile when no match is found
+      # @param <String> path is the reference to an asset file from another source
+      #   file, such as '/assets/styles.css'
+      # @return <String> the path to the content file for the referenced file,
+      #   such as '/assets/styles.scss'
+      def output_filename(input_path)
+        path = absolutize(input_path)
+
+        matching_item = site.items.find do |i|
+          next unless i.path # some items don't have an output path. Ignore those.
+          i.path.sub(/#{Nanoc3::Cachebuster::CACHEBUSTER_PREFIX}[a-zA-Z0-9]{9}(?=\.)/o, '') == path
+        end
+
+        # Raise an exception to indicate we should leave this reference alone
+        unless matching_item
+          raise Nanoc3::Cachebuster::NoSuchSourceFile, 'No source file found matching ' + input_path
+        end
+
+        # Make sure to keep or remove the first slash, as the input path
+        # does.
+        matching_item.path.tap do |p|
+          p.sub!(/^\//, '') unless input_path =~ /^\//
+        end
+      end
+
+      # Get the absolute path to a file, whereby absolute means relative to the root.
+      #
+      # We use the relative-to-root path to detect if our site contains an item
+      # that will be output to that location.
+      #
+      # @example Using an absolute input path in 'assets/styles.css'
+      #   absolutize('/assets/logo.png') # => '/assets/logo.png'
+      # @example Using a relative input path in 'assets/styles.css'
+      #   absolutize('logo.png') # => '/assets/logo.png'
+      #
+      # @param <String> path is the path of the file that is referred to in
+      #   an input file, such as a stylesheet or HTML page.
+      # @return <String> path to the same file as the input path but relative
+      #   to the site root.
+      def absolutize(path)
+        return path if path =~ /^\//
+        File.join(File.dirname(current_item[:content_filename]), path).sub(/^content/, '')
+      end
+    end
+
+    # The Css strategy looks for CSS-style external references that use the
+    # url() syntax. This will typically cover any @import statements and
+    # references to images.
+    class Css < Strategy
+      REGEX = /
+        url\(          # Start with the literal url(
+        ('|"|)         # Then either a single, double or no quote at all
+        (
+          ([^'")]+)    # The file basename, and below the extension
+          \.(#{Nanoc3::Cachebuster::FILETYPES_TO_FINGERPRINT.join('|')})
+        )
+        \1             # Repeat the same quote as at the start
+        \)             # And cose the url()
+      /ix
+
+      def apply(m, quote, filename, basename, extension)
+        m.sub(filename, output_filename(filename))
+      end
+    end
+
+    # The Html strategy looks for HTML-style attributes in the item source code,
+    # picking up the values of href and src attributes. This will typically cover
+    # links, stylesheets, images and javascripts.
+    class Html < Strategy
+      REGEX = /
+        (href|src)        # Look for either an href="" or src="" attribute
+        =                 # ...followed by an =
+        ("|'|)            # Then either a single, double or no quote at all
+        (                 # Capture the entire reference
+          [^'"]+          # Anything but something that would close the attribute
+                          # And then the extension:
+          (\.(?:#{Nanoc3::Cachebuster::FILETYPES_TO_FINGERPRINT.join('|')}))
+        )
+        \2                # Repeat the opening quote
+      /ix
+
+      def apply(m, attribute, quote, filename, extension)
+        %Q{#{attribute}=#{quote}#{output_filename(filename)}#{quote}}
+      end
+    end
+  end
+end
+

data/lib/nanoc3/cachebuster/version.rb

@@ -0,0 +1,5 @@
+module Nanoc3
+  module Cachebuster
+    VERSION = '0.1.0'
+  end
+end

data/lib/nanoc3/cachebuster.rb

@@ -0,0 +1,44 @@
+require 'nanoc3'
+require 'digest'
+
+module Nanoc3
+  module Cachebuster
+    autoload :VERSION,  'cachebuster/version'
+
+    # List of file extensions that the routing system should regard
+    # as needing a fingerprint. These are input file extensions, so
+    # we also include the extensions used by popular preprocessors.
+    FILETYPES_TO_FINGERPRINT = %w[css js scss sass less coffee html htm png jpg jpeg gif]
+
+    # List of file extensions that should be considered css. This is used
+    # to determine what filtering strategy to use when none is explicitly
+    # set.
+    FILETYPES_CONSIDERED_CSS = %w[css js scss sass less]
+
+    # Value prepended to the file fingerprint, to identify it as a cache buster.
+    CACHEBUSTER_PREFIX = '-cb'
+
+    # Custom exception that might be raised by the rewriting strategies when
+    # there can be no source file found for the reference that it found that
+    # might need rewriting.
+    #
+    # This exception should never bubble up from the filter.
+    NoSuchSourceFile = Class.new(Exception)
+
+    # Custom exception that will be raised when trying to use a filtering
+    # strategy that does not exist. This will bubble up to the end user.
+    NoSuchStrategy = Class.new(Exception)
+
+    def self.should_apply_fingerprint_to_file?(item)
+      FILETYPES_TO_FINGERPRINT.include? item[:extension]
+    end
+
+    def self.fingerprint_file(filename, length = 8)
+      CACHEBUSTER_PREFIX + Digest::MD5.hexdigest(File.read(filename))[0..length.to_i]
+    end
+  end
+
+  require File.expand_path('../filters', __FILE__)
+  require File.expand_path('../helpers', __FILE__)
+  require File.expand_path('../cachebuster/strategy', __FILE__)
+end

data/lib/nanoc3/filters/cache_buster.rb

@@ -0,0 +1,33 @@
+module Nanoc3
+  module Filters
+    class CacheBuster < Nanoc3::Filter
+      identifier :cache_buster
+
+      def run(content, options = {})
+        kind = options[:strategy] || (stylesheet? ? :css : :html)
+        strategy = Nanoc3::Cachebuster::Strategy.for(kind , site, item)
+        content.gsub(strategy.class::REGEX) do |m|
+          begin
+            strategy.apply m, $1, $2, $3, $4
+          rescue Nanoc3::Cachebuster::NoSuchSourceFile
+            m
+          end
+        end
+      end
+
+    private
+
+      # See if the current item is a stylesheet.
+      #
+      # This is a simple check for filetypes, but you can override what strategy to use
+      # with the filter options. This provides a default.
+      #
+      # @see Nanoc3::Cachebuster::FILETYPES_CONSIDERED_CSS
+      # @return <Bool>
+      def stylesheet?
+        Nanoc3::Cachebuster::FILETYPES_CONSIDERED_CSS.include?(item[:extension].to_s)
+      end
+    end
+  end
+end
+

data/lib/nanoc3/filters.rb

@@ -0,0 +1,4 @@
+module Nanoc3::Filters
+  autoload 'CacheBuster', 'nanoc3/filters/cache_buster'
+  Nanoc3::Filter.register '::Nanoc3::Filters::CacheBuster', :cache_buster
+end

data/lib/nanoc3/helpers/cache_busting.rb

@@ -0,0 +1,32 @@
+module Nanoc3
+  module Helpers
+    module CacheBusting
+
+      # Test if we want to filter the output filename for a given item.
+      # This is logic used in the Rules file, but doesn't belong there.
+      #
+      # @example Determining whether to rewrite an output filename
+      #   # in your Rules file
+      #   route '/assets/*' do
+      #     hash = cachebust?(item) ? cachebusting_hash(item) : ''
+      #     item.identifier + hash + '.' + item[:extension]
+      #   end
+      #
+      # @param <Item> item is the item to test
+      # @return <Boolean>
+      def cachebust?(item)
+        Nanoc3::Cachebuster.should_apply_fingerprint_to_file?(item)
+      end
+
+      # Get a unique fingerprint for a file's content. This currently uses
+      # an MD5 hash of the file contents.
+      #
+      # @todo Also allow passing in an item rather than a path
+      # @param <String> filename is the path to the file to fingerprint.
+      # @return <String> file fingerprint
+      def fingerprint(filename)
+        Nanoc3::Cachebuster.fingerprint_file(filename)
+      end
+    end
+  end
+end

data/lib/nanoc3/helpers.rb

@@ -0,0 +1,3 @@
+module Nanoc3::Helpers
+  autoload 'CacheBusting', 'nanoc3/helpers/cache_busting'
+end

data/nanoc-cachebuster.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'nanoc3/cachebuster/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'nanoc-cachebuster'
+  s.version     = Nanoc3::Cachebuster::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Arjan van der Gaag']
+  s.email       = ['arjan@arjanvandergaag.nl']
+  s.homepage    = 'http://github.com/avdgaag/nanoc_cachebuster'
+  s.summary     = %q{Adds filters and helpers for cache busting to Nanoc}
+  s.description = <<-EOS
+Your website should use far-future expires headers on static assets, to make
+the best use of client-side caching. But when a file is cached, updates won't
+get picked up. Cache busting is the practice of making the filename of a
+cached asset unique to its content, so it can be cached without having to
+worry about future changes.
+
+This gem adds a filter and some helper methods to Nanoc, the static site
+generator, to simplify the process of making asset filenames unique. It helps
+you output fingerprinted filenames, and refer to them from your source files.
+
+It works on images, javascripts and stylesheets. It is extracted from the
+nanoc-template project at http://github.com/avdgaag/nanoc-template.
+EOS
+
+  s.rubyforge_project = 'nanoc-cachebuster'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+end

data/spec/nanoc3/filters/cache_buster_spec.rb

@@ -0,0 +1,247 @@
+require 'ostruct'
+
+class MockItem
+  attr_reader :path, :content
+
+  def self.css_file(content = 'example content')
+    new '/styles-cb123456789.css', content, { :extension => 'css', :content_filename => 'content/styles.css' }
+  end
+
+  def self.html_file(content = 'example content')
+    new '/output_file.html', content, { :extension => 'html', :content_filename => 'content/input_file.html' }
+  end
+
+  def self.image_file(input = '/foo.png', output = '/foo-cb123456789.png')
+    new output, 'hello, world', { :extension => 'png', :content_filename => input }
+  end
+
+  def self.image_file_routed_somewhere_else
+    image_file '/foo.png', '/folder/foo-cb123456789.png'
+  end
+
+  def self.image_file_unfiltered
+    image_file '/foo.png', '/foo.png'
+  end
+
+  def initialize(path, content, attributes = {})
+    @path, @content, @attributes = path, content, attributes
+  end
+
+  def identifier
+    File.basename(@path)
+  end
+
+  def [](k)
+    @attributes[k]
+  end
+end
+
+describe Nanoc3::Filters::CacheBuster do
+  before(:each) do
+    Digest::MD5.stub!(:hexdigest).and_return('123456789')
+  end
+
+  let(:subject) { Nanoc3::Filters::CacheBuster.new context }
+  let(:content) { item.content }
+  let(:item)    { MockItem.css_file }
+  let(:target)  { MockItem.image_file }
+  let(:items)   { [item, target] }
+  let(:site)    { OpenStruct.new({ :items => items }) }
+  let(:context) do
+    {
+        :site    => site,
+        :item    => item,
+        :content => content,
+        :items   => items
+    }
+  end
+
+  describe 'filter interface' do
+    it { should be_kind_of(Nanoc3::Filter) }
+    it { should respond_to(:run) }
+
+    it 'should accept a string and an options Hash' do
+      lambda { subject.run('foo', {}) }.should_not raise_error(ArgumentError)
+    end
+  end
+
+  def self.it_should_filter(replacements = {})
+    replacements.each do |original, busted|
+      it 'should add cache buster to reference' do
+        context[:content] = original
+        subject.run(original).should == busted
+      end
+    end
+  end
+
+  def self.it_should_not_filter(str)
+    it 'should not change the reference' do
+      context[:content] = str
+      subject.run(str).should == str
+    end
+  end
+
+  describe 'filtering CSS' do
+    let(:item) { MockItem.css_file }
+
+    describe 'when the file exists' do
+      before(:each) do
+        File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+      end
+
+      describe 'without quotes' do
+        it_should_filter %Q{background: url(foo.png);} => 'background: url(foo-cb123456789.png);'
+      end
+
+      describe 'with single quotes' do
+        it_should_filter %Q{background: url('foo.png');} => %Q{background: url('foo-cb123456789.png');}
+      end
+
+      describe 'with double quotes' do
+        it_should_filter %Q{background: url("foo.png");} => %Q{background: url("foo-cb123456789.png");}
+      end
+    end
+
+    describe 'when using an absolute path' do
+      let(:target) { MockItem.image_file '/foo.png', '/images/foo-cb123456789.png' }
+
+      before(:each) do
+        File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+      end
+
+      it_should_filter %Q{background: url("/images/foo.png");} => %Q{background: url("/images/foo-cb123456789.png");}
+    end
+
+    describe 'when using a relative path' do
+      let(:target) { MockItem.image_file '/foo.png', '/../images/foo-cb123456789.png' }
+
+      before(:each) do
+        File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+      end
+
+      it_should_filter %Q{background: url("../images/foo.png");} => %Q{background: url("../images/foo-cb123456789.png");}
+    end
+
+    describe 'when the file does not exist' do
+      let(:target) { MockItem.image_file_routed_somewhere_else }
+
+      it_should_not_filter %Q{background: url(foo.png);}
+    end
+
+    describe 'when the file is not cache busted' do
+      let(:target) { MockItem.image_file_unfiltered }
+
+      it_should_not_filter %Q{background: url(foo.png);}
+    end
+  end
+
+  describe 'filtering HTML' do
+    describe 'on the href attribute' do
+      let(:item) { MockItem.html_file '<link href="foo.png">' }
+
+      describe 'when the file exists' do
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        describe 'without quotes' do
+          it_should_filter %Q{<link href=foo.png>} => %Q{<link href=foo-cb123456789.png>}
+        end
+
+        describe 'with single quotes' do
+          it_should_filter %Q{<link href='foo.png'>} => %Q{<link href='foo-cb123456789.png'>}
+        end
+
+        describe 'with double quotes' do
+          it_should_filter %Q{<link href="foo.png">} => %Q{<link href="foo-cb123456789.png">}
+        end
+      end
+
+      describe 'when using an absolute path' do
+        let(:target) { MockItem.image_file '/foo.png', '/images/foo-cb123456789.png' }
+
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        it_should_filter %Q{<link href="/images/foo.png">} => %Q{<link href="/images/foo-cb123456789.png">}
+      end
+
+      describe 'when using a relative path' do
+        let(:target) { MockItem.image_file '/foo.png', '/../images/foo-cb123456789.png' }
+
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        it_should_filter %Q{<link href="../images/foo.png">} => %Q{<link href="../images/foo-cb123456789.png">}
+      end
+
+      describe 'when the file does not exist' do
+        let(:target) { MockItem.image_file_routed_somewhere_else }
+
+        it_should_not_filter '<link href="foo.png">'
+      end
+
+      describe 'when the file is not cache busted' do
+        let(:target) { MockItem.image_file_unfiltered }
+
+        it_should_not_filter '<link href="foo.png">'
+      end
+    end
+
+    describe 'on the src attribute' do
+      let(:item) { MockItem.html_file '<img src="foo.png">' }
+
+      describe 'when the file exists' do
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        describe 'without quotes' do
+          it_should_filter %Q{<img src=foo.png>} => %Q{<img src=foo-cb123456789.png>}
+        end
+
+        describe 'with single quotes' do
+          it_should_filter %Q{<img src='foo.png'>} => %Q{<img src='foo-cb123456789.png'>}
+        end
+
+        describe 'with double quotes' do
+          it_should_filter %Q{<img src="foo.png">} => %Q{<img src="foo-cb123456789.png">}
+        end
+      end
+
+      describe 'when using an absolute path' do
+        let(:target) { MockItem.image_file '/foo.png', '/images/foo-cb123456789.png' }
+
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        it_should_filter %Q{<img src="/images/foo.png">} => %Q{<img src="/images/foo-cb123456789.png">}
+      end
+
+      describe 'when using a relative path' do
+        let(:target) { MockItem.image_file '/foo.png', '/../images/foo-cb123456789.png' }
+
+        before(:each) do
+          File.stub!(:read).with(File.join(Dir.pwd, 'content', 'foo.png')).and_return(context[:content])
+        end
+
+        it_should_filter %Q{<img src="../images/foo.png">} => %Q{<img src="../images/foo-cb123456789.png">}
+      end
+
+      describe 'when the file does not exist' do
+        let(:target) { MockItem.image_file_routed_somewhere_else }
+
+        it_should_not_filter '<img src="foo.png">'
+      end
+
+      describe 'when the file is not cache busted' do
+        let(:target) { MockItem.image_file_unfiltered }
+
+        it_should_not_filter '<img src="foo.png">'
+      end
+    end
+  end
+end

data/spec/nanoc3/helpers/cache_busting_spec.rb

@@ -0,0 +1,22 @@
+describe Nanoc3::Helpers::CacheBusting do
+  let(:subject) do
+    o = Object.new
+    o.extend Nanoc3::Helpers::CacheBusting
+  end
+
+  describe '#should_cachebust?' do
+    %w{png jpg jpeg gif css js scss sass less coffee html htm}.each do |extension|
+      it "should add fingerprint to #{extension} files" do
+        subject.cachebust?({ :extension => extension }).should be_true
+      end
+    end
+  end
+
+  describe '#fingerprint' do
+    it 'should calculate a checksum of the source file' do
+      File.should_receive(:read).with('foo').and_return('baz')
+      Digest::MD5.should_receive(:hexdigest).with('baz').and_return('bar')
+      subject.fingerprint('foo').should == '-cbbar'
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'nanoc3/cachebuster'
+

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: nanoc-cachebuster
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Arjan van der Gaag
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-21 00:00:00 Z
+dependencies: []
+
+description: |
+  Your website should use far-future expires headers on static assets, to make
+  the best use of client-side caching. But when a file is cached, updates won't
+  get picked up. Cache busting is the practice of making the filename of a
+  cached asset unique to its content, so it can be cached without having to
+  worry about future changes.
+  
+  This gem adds a filter and some helper methods to Nanoc, the static site
+  generator, to simplify the process of making asset filenames unique. It helps
+  you output fingerprinted filenames, and refer to them from your source files.
+  
+  It works on images, javascripts and stylesheets. It is extracted from the
+  nanoc-template project at http://github.com/avdgaag/nanoc-template.
+
+email: 
+- arjan@arjanvandergaag.nl
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- HISTORY.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/nanoc3/cachebuster.rb
+- lib/nanoc3/cachebuster/strategy.rb
+- lib/nanoc3/cachebuster/version.rb
+- lib/nanoc3/filters.rb
+- lib/nanoc3/filters/cache_buster.rb
+- lib/nanoc3/helpers.rb
+- lib/nanoc3/helpers/cache_busting.rb
+- nanoc-cachebuster.gemspec
+- spec/nanoc3/filters/cache_buster_spec.rb
+- spec/nanoc3/helpers/cache_busting_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/avdgaag/nanoc_cachebuster
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: nanoc-cachebuster
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Adds filters and helpers for cache busting to Nanoc
+test_files: 
+- spec/nanoc3/filters/cache_buster_spec.rb
+- spec/nanoc3/helpers/cache_busting_spec.rb
+- spec/spec_helper.rb