jekyll-minibundle 1.0.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YmU4ZTUwM2ZlNTlhNGI1OGFjMTg4OGRhNDEyNWYwOWUyYjI1OWUwMQ==
+  data.tar.gz: !binary |-
+    ZDdiN2RjN2JiMDY3Yjc4ODA4MTI2YTA5YWVlY2RkMzM3NGFhOTMzYg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MGFiYmJhNGY1MTRhOTRiYWYxM2FkOWQxYmE5YzU0ZGM5NjMwMTkxNDRlY2Q0
+    MWQxZmIwZTY5NWY5YTg5ZGIzYjkyMjlkNzk4Yjg1NTNlN2QzMzA5ZjU3NDZl
+    OTcwODM2ZjU3YjQ1NGFjNmRlYzcyNDU0NDg5Y2I4YTQ2YWZiYmE=
+  data.tar.gz: !binary |-
+    ZWZjNmNlZmMxZTQ3MmFkNGY0YzExYmY1NGFjM2VmZjVkMzFiZjQxMTY1ODNi
+    OWVhODdjNTIzM2E5NjRkMDNjMDA4Njc1NjI4MmVjOTZjMjlkNjVlZWJhZWIx
+    MWE3YzVmZThlMmQ0YzIxODgxZmFiZmQ2ODg4NzQ2M2Q0YmE4M2E=

data/{History.md → CHANGELOG.md}

@@ -1,17 +1,25 @@
-### 1.0.0 / 2013-02-15
+# 1.1.0 / 2013-02-27
+
+* `ministamp` tag omits fingerprint in development mode
+* Clarify documentation
+* Comply with (Gemnasium) conventions for changelogs (@tmatilai)
+* Bug fix: do not bundle assets when nonrelated files change
+* Bug fix: do not bundle assets twice upon startup
+
+# 1.0.0 / 2013-02-15
 
 * Add development mode, where `minibundle` block will copy each asset
   as-is to the destination directory
 * Clarify documentation
 * Increase test coverage
 
-### 0.2.0 / 2012-12-15
+# 0.2.0 / 2012-12-15
 
 * Escape the values of custom attributes given in `minibundle` block
 * Add semicolons between each JavaScript asset in bundling
 * Show error in page output if asset bundling command failed
 
-### 0.1.0 / 2012-12-07
+# 0.1.0 / 2012-12-07
 
 * Add `ministamp` tag and `minibundle` block for Jekyll
 * First release

data/README.md

@@ -0,0 +1,157 @@
+# Jekyll Minibundle plugin
+
+A minimalistic plugin for bundling assets to
+[Jekyll](https://github.com/mojombo/jekyll)'s site generation
+directory.
+
+In addition to the plugin itself, you need a minification tool
+supporting standard unix input and output. There are no gem
+dependencies at runtime.
+
+Tested with Ruby MRI 1.9.3. Ruby 1.8 is *not* supported.
+
+[![Build Status](https://secure.travis-ci.org/tkareine/jekyll-minibundle.png)](http://travis-ci.org/tkareine/jekyll-minibundle)
+
+# Features
+
+There are two features: asset fingerprinting with MD5 digest over the
+contents of the asset, and asset bundling combined with the first
+feature.
+
+Asset bundling consists of concatenation and minification. The plugin
+implements concatenation and leaves up to you to choose the
+minification tool. [UglifyJS2](https://github.com/mishoo/UglifyJS2) is
+a good and fast minifier. The plugin connects to the minifier with
+standard unix pipe, feeding asset file contents to it in desired order
+via standard input, and reads the result from standard output.
+
+Why is this good? Well, a fingerprint in asset's path is the
+[recommended way](https://developers.google.com/speed/docs/best-practices/caching)
+to handle caching of static resources, because you can allow caching
+the asset forever. Calculating MD5 digest over the contents of the
+asset is fast and the resulting digest is reasonably unique to be
+generated automatically.
+
+Asset bundling is good for reducing the number of requests to the
+backend upon page load. The minification of stylesheets and JavaScript
+sources makes asset sizes smaller and thus faster to load over
+network.
+
+# Usage
+
+The plugin is shipped as a
+[RubyGem](https://rubygems.org/gems/jekyll-minibundle):
+
+``` bash
+$ gem install jekyll-minibundle
+```
+
+Add file `_plugins/minibundle.rb` to your Jekyll site project with
+this line:
+
+``` ruby
+require 'jekyll/minibundle'
+```
+
+## Asset fingerprinting
+
+Asset fingerprinting is intended to be used together with
+[Compass](http://compass-style.org/) and other similar asset
+generation tools that have their own configuration for input sources.
+
+Configure Compass to take inputs from `_assets/styles/*.scss` and to
+put output to `_tmp/site.css`. Use `ministamp` tag to copy the
+processed style asset to the generated site:
+
+``` html
+<link href="{% ministamp _tmp/site.css assets/site.css %}" rel="stylesheet" media="screen, projection">
+```
+
+Output, containing the MD5 digest of the file in the filename:
+
+``` html
+<link href="assets/site-390be921ee0eff063817bb5ef2954300.css" rel="stylesheet" media="screen, projection">
+```
+
+This feature does not require any external tools.
+
+## Asset bundling
+
+This is a straightforward way to bundle assets with any minification
+tool that supports reading input from STDIN and writing the output to
+STDOUT. You write the configuration for input sources directly into
+the content file where you want the markup tag for the bundle file to
+appear. The outcome will be a markup tag containing the path to the
+bundle file, and the generated site will have the bundle file in that
+path. The MD5 digest of the file will be included in the filename.
+
+Place `minibundle` block with configuration into your content file
+where you want the generated markup to appear. For example, to bundle
+a set of JavaScript sources:
+
+``` text
+{% minibundle js %}
+source_dir: _assets/scripts
+destination_path: assets/site
+assets:
+  - dependency
+  - app
+attributes:
+  id: my-scripts
+{% endminibundle %}
+```
+
+Then, specify the command for launching your favorite minifier in
+`$JEKYLL_MINIBUNDLE_CMD_JS` environment variable. For example, when
+launching Jekyll:
+
+``` bash
+$ JEKYLL_MINIBUNDLE_CMD_JS='./node_modules/.bin/uglifyjs --' jekyll
+```
+
+You can pass custom attributes to the generated markup with
+`attributes` map in the configuration.
+
+Output in the content file:
+
+``` html
+<script src="assets/site-8e764372a0dbd296033cb2a416f064b5.js" type="text/javascript" id="my-scripts"></script>
+```
+
+For bundling CSS assets, you use `css` as the argument to `minibundle` block:
+
+``` text
+{% minibundle css %}
+source_dir: _assets/styles
+destination_path: assets/site
+assets:
+  - reset
+  - common
+attributes:
+  media: screen
+{% endminibundle %}
+```
+
+And then specify the command for launching bundling in
+`$JEKYLL_MINIBUNDLE_CMD_CSS` environment variable.
+
+## Development mode
+
+The plugin has one more trick in its sleeves. If you set environment
+variable `JEKYLL_MINIBUNDLE_MODE` to `development`, then the plugin
+will copy asset files as is to the destination directory (using
+`destination_path` as directory for `minibundle` block), and omit
+fingerprinting. This is useful in development workflow, where you need
+the filenames and line numbers of the original asset sources.
+
+``` bash
+$ JEKYLL_MINIBUNDLE_MODE=development jekyll --auto --server
+```
+
+# Example site
+
+See the contents of `test/fixture/site` directory.
+
+# License
+
+MIT. See `LICENSE.txt`.

data/RELEASING.txt

@@ -0,0 +1,11 @@
+In order to release, do
+
+$EDITOR lib/jekyll/minibundle/version.rb  # update version number
+$EDITOR CHANGELOG.md                      # describe a summary of changes since last release
+git diff                                  # review the changes
+rake gem:build                            # check that tests pass
+git add -p
+git commit -m 'Release <version>'
+git tag <version>
+git push --tags origin master
+gem push jekyll-minibundle-<version>.gem

data/Rakefile

@@ -38,7 +38,7 @@ task :test do
   tests = Dir['test/**/*_test.rb'].
     map { |file| %r{^test/(.+)\.rb$}.match(file)[1] }.
     shelljoin
-  test_cmd = %{bundle exec ruby -e 'ARGV.each { |f| require f }' #{tests}}
+  test_cmd = %{ruby -e 'ARGV.each { |f| require f }' #{tests}}
   sh(get_minibundle_env('RUBYLIB' => 'lib:test'), test_cmd)
 end
 

data/jekyll-minibundle.gemspec

@@ -0,0 +1,70 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'lib/jekyll/minibundle/version'))
+
+Gem::Specification.new do |s|
+  s.name        = 'jekyll-minibundle'
+  s.version     = Jekyll::Minibundle::VERSION
+  s.summary     = 'A minimalistic asset bundling plugin for Jekyll'
+  s.authors     = ['Tuomas Kareinen']
+  s.email       = 'tkareine@gmail.com'
+  s.homepage    = 'https://github.com/tkareine/jekyll-minibundle'
+  s.licenses    = %w{MIT}
+
+  s.description = <<-END
+A minimalistic asset bundling plugin for Jekyll, requiring only your
+bundling tool of choice (no other dependencies, not even other gems).
+Provides asset bundling and filename stamping with MD5 digest.
+  END
+
+  s.files = %w{
+    CHANGELOG.md
+    LICENSE.txt
+    README.md
+    RELEASING.txt
+    Rakefile
+    jekyll-minibundle.gemspec
+    lib/jekyll/minibundle/asset_bundle.rb
+    lib/jekyll/minibundle/asset_file_operations.rb
+    lib/jekyll/minibundle/asset_file_paths.rb
+    lib/jekyll/minibundle/asset_stamp.rb
+    lib/jekyll/minibundle/asset_tag_markup.rb
+    lib/jekyll/minibundle/bundle_file.rb
+    lib/jekyll/minibundle/development_file.rb
+    lib/jekyll/minibundle/development_file_collection.rb
+    lib/jekyll/minibundle/environment.rb
+    lib/jekyll/minibundle/mini_bundle_block.rb
+    lib/jekyll/minibundle/mini_stamp_tag.rb
+    lib/jekyll/minibundle/stamp_file.rb
+    lib/jekyll/minibundle/version.rb
+    lib/jekyll/minibundle.rb
+  }
+
+  s.test_files = %w{
+    test/fixture/site/_assets/scripts/app.js
+    test/fixture/site/_assets/scripts/dependency.js
+    test/fixture/site/_assets/styles/common.css
+    test/fixture/site/_assets/styles/reset.css
+    test/fixture/site/_bin/remove_comments
+    test/fixture/site/_bin/with_count
+    test/fixture/site/_plugins/minibundle.rb
+    test/fixture/site/_tmp/site.css
+    test/fixture/site/index.html
+    test/integration/minibundle_development_mode_test.rb
+    test/integration/minibundle_production_mode_test.rb
+    test/integration/ministamp_test.rb
+    test/support/fixture_config.rb
+    test/support/test_case.rb
+    test/unit/asset_bundle_test.rb
+    test/unit/asset_tag_markup_test.rb
+    test/unit/bundle_file_test.rb
+    test/unit/stamp_file_test.rb
+  }
+
+  s.add_development_dependency 'jekyll',   '~> 0.12.0'
+  s.add_development_dependency 'minitest', '~> 4.6.0'
+  s.add_development_dependency 'nokogiri', '~> 1.5.6'
+  s.add_development_dependency 'rake',     '~> 10.0.2'
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.rdoc_options << '--line-numbers' << '--title' << s.name << '--exclude' << 'test'
+end

data/lib/jekyll/minibundle/asset_bundle.rb

@@ -1,4 +1,5 @@
 require 'tempfile'
+require 'jekyll/minibundle/environment'
 
 module Jekyll::Minibundle
   class AssetBundle
@@ -27,10 +28,7 @@ module Jekyll::Minibundle
     private
 
     def bundling_cmd
-      key = "JEKYLL_MINIBUNDLE_CMD_#{@type.upcase}"
-      cmd = ENV[key]
-      raise "You need to set bundling command in $#{key}" if !cmd
-      cmd
+      Environment.command_for @type
     end
 
     def pipe_bundling_to_temp_file(cmd)

data/lib/jekyll/minibundle/asset_file_paths.rb

@@ -4,12 +4,12 @@ module Jekyll::Minibundle
       asset_source_path
     end
 
-    def asset_path
+    def asset_destination_path
       File.join asset_destination_dir, asset_destination_basename
     end
 
     def destination(site_destination_dir)
-      File.join site_destination_dir, asset_destination_dir, asset_destination_basename
+      File.join site_destination_dir, asset_destination_path
     end
 
     def destination_exists?(site_destination_dir)

data/lib/jekyll/minibundle/bundle_file.rb

@@ -7,72 +7,88 @@ module Jekyll::Minibundle
   class BundleFile
     include AssetFileOperations
 
-    @@mtimes = {}
+    def self.clear_cache
+      @@mtimes = {}
+      @@writes_after_mtime_updates = Hash.new false
+      @@asset_bundles = {}
+    end
+
+    clear_cache
 
     def initialize(config)
       @type = config['type']
       @site_source_dir = config['site_dir']
       asset_source_dir = File.join @site_source_dir, config['source_dir']
       @assets = config['assets'].map { |asset_path| File.join asset_source_dir, "#{asset_path}.#{@type}" }
-      @asset_destination_path = config['destination_path']
+      @destination_path = config['destination_path']
       @attributes = config['attributes']
     end
 
+    def markup
+      # we must rebundle here, if at all, in order to make sure the
+      # markup and generated file have the same fingerprint
+      rebundle_assets if modified?
+      AssetTagMarkup.make_markup @type, asset_destination_path, @attributes
+    end
+
     def path
       asset_bundle.path
     end
 
-    def asset_path
-      "#{@asset_destination_path}-#{asset_stamp}.#{@type}"
+    def asset_destination_path
+      "#{@destination_path}-#{asset_stamp}.#{@type}"
     end
 
     def destination(site_destination_dir)
-      File.join site_destination_dir, asset_path
+      File.join site_destination_dir, asset_destination_path
     end
 
     def mtime
-      @assets.max { |f| File.stat(f).mtime.to_i }
+      @assets.map { |f| File.stat(f).mtime.to_i }.max
     end
 
     def modified?
-      @@mtimes[path] != mtime
+      @@mtimes[asset_destination_canonical_path] != mtime
     end
 
-    def write(site_destination_dir)
-      is_modified = modified?
-
-      rebundle_assets if is_modified
+    def destination_written_after_mtime_update?
+      @@writes_after_mtime_updates[asset_destination_canonical_path]
+    end
 
-      if File.exists?(destination(site_destination_dir)) && !is_modified
+    def write(site_destination_dir)
+      if File.exists?(destination(site_destination_dir)) && destination_written_after_mtime_update?
         false
       else
-        update_mtime
         write_destination site_destination_dir
+        @@writes_after_mtime_updates[asset_destination_canonical_path] = true
         true
       end
     end
 
-    def markup
-      AssetTagMarkup.make_markup @type, asset_path, @attributes
-    end
-
     private
 
+    def asset_destination_canonical_path
+      "#{@destination_path}.#{@type}"
+    end
+
     def asset_stamp
-      @asset_stamp ||= AssetStamp.from_file(path)
+      @asset_stamp ||= AssetStamp.from_file path
     end
 
     def asset_bundle
-      @asset_bundle ||= AssetBundle.new(@type, @assets, @site_source_dir).make_bundle
+      @@asset_bundles[asset_destination_canonical_path] ||= AssetBundle.new(@type, @assets, @site_source_dir)
     end
 
     def rebundle_assets
       @asset_stamp = nil
       asset_bundle.make_bundle
+      update_mtime
     end
 
     def update_mtime
-      @@mtimes[path] = mtime
+      p = asset_destination_canonical_path
+      @@mtimes[p] = mtime
+      @@writes_after_mtime_updates[p] = false
     end
   end
 end

data/lib/jekyll/minibundle/development_file.rb

@@ -24,16 +24,10 @@ module Jekyll::Minibundle
       if destination_exists?(site_destination_dir) && !modified?
         false
       else
-        update_mtime
+        @@mtimes[path] = mtime
         write_destination site_destination_dir
         true
       end
     end
-
-    private
-
-    def update_mtime
-      @@mtimes[path] = mtime
-    end
   end
 end