Jekyll Asset Bundler is a Jekyll plugin for... bundling assets. It is hacked onto... I mean, utilizes deep integration with Jekyll for a seamless deployment experience.
Copy or link asset_bundler.rb into your _plugins folder
for your Jekyll project.
If your Jekyll project is in a git repository, you can easily manage your plugins by utilizing git submodules.
To install this plugin as a git submodule:
git submodule add git://github.com/moshen/jekyll-asset_bundler.git _plugins/asset_bundler
To update:
cd _plugins/asset_bundler
git pull origin master
Currently only supports absolute asset paths in relation to your
source directory. For example: /css/mystyle.css looks for a file
in my_source_dir/css/mystyle.css.
- Works with Octopress
- Custom commands for bundle compression
- Compressed bundle caching
- Bundling and caching of remote assets
- Dev mode, for easy site development with all assets
- Dev-only asset inclusion
- Relative paths support
- CoffeeScript and LessCSS compilation support
v0.05 - Changed from using Liquid::Tags to Liquid::Blocks. This will break on existing bundle markup if you upgrade.
Why change it? Well, Liquid::Tags have to be on one line, whereas Liquid::Blocks do not, also it opens up some more flexibility, as additional options could be included in the tag text.
v0.08 - Changed the cdn config parameter to server_url in order to be
more generic. For the time being, cdn still works (see below).
Why change it? There seemed to be a little confusion about the parameter name and what the parameter does.
v0.11 - jekyll --watch now turns on dev mode. Removed code for
compatibility with versions of Jekyll pre 1.0.
Why change it? jekyll --watch isn't really supported by the plugin anyway.
Also, Jekyll is changing and I don't want this to be any more of an
unmaintainable mess.
Consider this beta software, though for small Jekyll sites you should have no problem using it.
Once installed in your _plugins folder Jekyll Asset Bundler provides
Liquid::Blocks to use which will generate the appropriate
markup for including JavaScript and CSS.
Each of the following blocks consumes a YAML
formatted array.
{% bundle %} [/js/main.js, /js/somethingelse.js] {% endbundle %}
Is equal to:
{% bundle %}
- /js/main.js
- /js/somethingelse.js
{% endbundle %}
Remote assets can also be bundled:
{% bundle %}
- http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7.2/jquery.min.js
- //cdnjs.cloudflare.com/ajax/libs/underscore.js/1.3.1/underscore-min.js
- https://cdnjs.cloudflare.com/ajax/libs/backbone.js/0.9.2/backbone-min.js
- /js/my_local_javascript.js
{% endbundle %}
Remote assets will be cached in the _asset_bundler_cache folder
(in the same directory as your _plugins folder). If you want to
regenerate cached items, delete the cache folder.
The bundle tag will concatenate the provided scripts and make a hash of
the result. This hash is used as a filename. The Bundle is then compressed
(if desired), and the final result cached in the _asset_bundler_cache folder.
Therefore, the bundle is only recreated and compressed again if the source
files have been modified. This greatly speeds up future site builds.
Note: Asset Bundler makes no attempt to clean up the cache folder. If it has grown too large, simply delete it.
The proper markup is finally inserted to include your bundle file.
{% bundle_glob %}
- /js/*.js
- /css/*.css
{% endbundle_glob %}
The bundle_glob tag uses the
Ruby Dir.glob
method to include multiple assets.
WARNING: assets will be included in alphanumeric order,
this may screw something up.
{% dev_assets %}
- /js/less.js
{% enddev_assets %}
The dev_assets tag includes the normal markup for the referenced
assets only in 'dev mode'. The array items can either be local files
or urls for external scripts and are included as-is.
At any other time, it does nothing.
In a future version (hopefully soon), this will play a role in
utilizing things like LessCSS and CoffeeScript.
Some behavior can be modified with settings in your _config.yml. The
following represents the default configuration:
asset_bundler:
compress:
js: false
css: false
base_path: /bundles/
server_url:
remove_bundled: false
dev: false
bundle_name: false
markup_templates:
js: "<script type='text/javascript' src='{{url}}'></script>\n"
css: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"
Here is a breakdown of each configuration option under the top level
asset_bundler key.
Compresses nothing by default. Change the js and css keys to
modify compression behavior.
To compress with the yui-compressor gem, use 'yui' here, to compress with the closure compiler gem, use 'closure' here. Use 'closure_advanced' to compress with the closure compiler gem using ADVANCED_OPTIMIZATIONS.
compress:
js: yui
To compress with a system command, enter it for the appropriate asset type:
compress:
js: uglifyjs :infile -o :outfile -c
This example will run a uglifyjs command from your PATH
while substituting :outfile and :infile for temporary files
stored in _asset_bundler_cache.
If either :outfile or :infile are omitted, stdout and stdin will be used. WARNING, stdin and stdout are done with IO.popen , which doesn't work on Windows
Note: Some have reported other issues when using the yui-compressor or closure compiler gems on Windows. If you having trouble on windows, try specifying a command as outlined above.
Takes the exact same arguments as js:, with the exception
of the Google Closure Compiler ( it's JavaScript only ).
When using closure compiler with ADVANCED_OPTIMIZATIONS enabled (see above), externs files can be passed to the compiler:
js_externs:
- path/to/externs.js
- other/path/to/externs.js
Where the bundles will be copied within your destination folder.
Default: /bundles/.
NOTE: In v0.07 and earlier this setting was cdn. The cdn key still
works and will act as an alias. However, if the server_url key is set, it
will override cdn.
The root path of your server_url or CDN (if you use one). For example: http://my-cdn.cloudfront.net/
Jekyll Asset Bundler checks to make sure that this setting ends in a slash.
Default: (blank).
If set to true, will remove the files included in your bundles from the destination folder.
Default: false.
Specifies one or more named bundles to be created. No markup is created for named bundles, so these must be referenced manually.
Named bundles are especially useful, when not referenced statically, but loaded dynamically. Otherwise, consider using anonymous bundles (defined inline as liquid block) instead.
The file extension of the bundle name must match the content type (currently
either js or css).
named_bundles:
first_bundle.js:
- path/to/file.js
- other/file.js
second_bundle.js:
- path/to/file.js
- path/to/other.js
Default: {} (none).
NOTE: In v0.10 and earlier, dev mode was not enabled automatically for
--auto or --watch mode.
If set to true, enables dev mode. When dev mode is active, no anonymous
bundles (defined as liquid block) are created and all the referenced files are
included individually without modification. Nevertheless, named bundles
(defined in _config.yml using the named_bundles option) are created and
merged, but no compression will be applied.
Dev mode is also automatically enabled when using
jekyll server, jekyll --watch or when a top level configuration key: dev
is set to true.
Default: false.
Use the relevant markup_template options to override the default templates
for inserting bundles. Each option is parsed with Liquid::Template.parse
and passed a url (String) parameter.
Note: if you want newlines to be passed in properly, be sure to quote your
templates in _config.yml.
The default JavaScript markup is fairly verbose. If you would like a modern
replacement, try "<script src='{{url}}'></script>\n".
Default: "<script type='text/javascript' src='{{url}}'></script>\n"
The default CSS is also verbose. If you would like a modern
replacement, try "<link rel=stylesheet href='{{url}}'>\n".
Default: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"
Jekyll Asset Bundler uses the yui-compressor or closure-compiler gems (when configured) and (obviously) Jekyll.
Colin Kennedy, moshen on GitHub
MIT, see LICENSE file.