Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Assets pipelines for Jekyll.

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

Jekyll::AssetsPlugin

Build Status Dependency Status Code Climate

Jekyll plugin, that adds Rails-alike assets pipeline, that means that:

  • It allows you to write javascript/css assets in other languages such as CoffeeScript, Sass, Less and ERB.
  • It allows you to specify dependencies between your assets and automatically concatenates them.
  • It allows you to minify/compress your JavaScript and CSS assets using compressor you like: YUI, SASS, Uglifier or no compression at all.
  • It supports JavaScript templates for client-side rendering of strings or markup. JavaScript templates have the special format extension .jst and are compiled to JavaScript functions.
  • Automaticaly adds MD5 fingerprint suffix for cache busting. That means that your app.css will become app-908e25f4bf641868d8683022a5b62f54.css.
  • Compass and Bourbon built-in support. See "Custom Vendors" below.

Jekyll-Assets uses fabulous Sprockets under the hood, so you may refer to Rails guide about Asset Pipeline for detailed information about amazing features it gives you.

Note: You must have an ExecJS supported runtime in order to use CoffeeScript.

For a quick start check out jekyll-assets introduction that shows how to use it step by step. Also you might want to take a look on my blog sources as a real-world example as well.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-assets'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-assets

How to Use Jekyll-Assets

First of all make sure to require it. Common practice is to add following line into _plugins/ext.rb file:

require "jekyll-assets"

Once plugin installed, you'll have following Liquid tags available:

  • {% javascript app %}: Generates <script> tag for app.js
  • {% stylesheet app %}: Generates <link> tag for app.css
  • {% asset_path logo.png %}: Returns resulting URL for logo.png
  • {% asset app.css %}: Returns compiled body of app.css

Also you'll have complimentary Liquid filters as well:

  • {{ 'app' | javascript }}: Generates <script> tag for app.js
  • {{ 'app' | stylesheet }}: Generates <link> tag for app.css
  • {{ 'logo.png' | asset_path }}: Returns resulting URL for logo.png
  • {{ 'app.css' | asset }}: Returns compiled body of app.css

Filters are used mostly to render tag (or asset source) using variable that holds value of asset logical path rather than specifiyng it directly. Here's an example that speaks for itself:

{% if page.custom_css %}{{ page.custom_css | stylesheet }}{% endif %}

All compiled assets will be stored under assets/ dir of generated site.

Pipeline assets should be under your sources directory of Jekyll site. When a file is referenced with liquid tag or with helper from another asset, Sprockets searches the three default asset locations for it: _assets/images, _assets/javascripts and _assets/stylesheets.

For example these files:

_assets/stylesheets/app.css
_assets/javascripts/app.js
_assets/javascripts/vendor/jquery.js

would be referenced like this:

{% stylesheet app %}
{% javascript app %}
{% javascript vendor/jquery %}

You might want to require vendor/jquery.js into your app.js. To do so, just put following line in the beginning of your app.js to get it concatenated:

//= require vendor/jquery

$(function () {
  alert('I love BIG BOOKS!');
});

If you want to use CoffeScript, just add .coffee suffix to the file you want and you're good to go. For example, here's how your app.js.coffe might look like:

#= require vendor/jquery

$ ->
  alert 'I love BIG BOOKS! And small ones too!'

Notice, that vendor/jquery is not required to be coffee script. You can easily mix CoffeeScript and vanilla JavaScript, CSS and SCSS and SASS and LESS. The difference is only in comments styles used with directives.

See detailes information about these directives below.

You might also want your stylesheets and javascripts to be minified. In this case just install uglifier gem and add following lines into your config.yml:

assets:
  compress:
    js:   uglifier
    css:  sass

If you want to use YUI compressor for minification, install yui-compressor gem and put yui in place of uglifier and/or sass in the config file.

Let's go crazy now! Assume you want your blog's body background color to be white all the time, but red if you compiled your web-site in December. Just add .erb suffix extension and you can use ruby in your asset like this:

// file: _assets/stylesheets/app.css.sass.erb

body
  background-color: <%= (12 == Date.today.month) ? "red" : "white" %>

Note that all assets are pre-processed with Liquid. So if you just need to output asset URL within your javascript/coffeescript or pure css, you don't need to use ERB, just use asset_path Liquid tag same as you do it in your layouts/pages. See "Liquid Assets Pre-processing" for more details.

Want more? Sure, here you are. You can use JavaScript templating with EJS or ECO for example. Create a file _assets/javascripts/hello.jst.ejs with following contents:

<p>Hello, <span><%= name %></span>!</p>
<p><%= info %></p>

Then use it in your app.js file like this:

#= require vendor/jquery
#= require hello

$ ->
  $("body").html JST["hello"]
    name: "ixti"
    info: "I love BIG BOOKS! And small ones too!"

Finally, you might want to store your assets on Amazon S3 or any CDN service you like. As said previously, all compiled/processed assets got special MD5 checksum appended to their original filenames. So, for example, your app.js.coffee will become something like:

app-4f41243847da693a4f356c0486114bc6.js

By default, generated URLs will have /assets/ prefixes, but you will want to change this if you are going to host assets somewhere else. This can be easily changed via configuration:

assets:
  baseurl: //my.super-cool-cdn.com/

Liquid Assets Pre-processing

All javascript and stylesheet assets are preprocessed with Liquid automagically. That means that you can use all liquid tags available to you in Jekyll, but most like;y you would want it for asset_path tag only:

# file: _assets/javascripts/app.js.coffee
yepnope.load "{% asset_path app.css %}"

Custom Vendors

Sometimes you would like to have some 3rd-party vendors. For this purposes, normally all you have to do is to override default assets sources in config:

assets:
  sources:
    - _assets/images
    - _assets/javascripts
    - _assets/stylesheets
    - _vendors/bootstrap/stylesheets
    - _vendors/bootstrap/javascripts

But sometimes this is not enough. For example, with compass. As jekyll-assets uses Sprockets internally, you can simply append "global" paths into it. Just add following line into your _plugins/ext.rb file:

require "sprockets"

Sprockets.append_path "/my/vendor"

That's it, now jekyll-assets will try to look for assets inside /my/vendor path first.

Built-in Vendors Support

For your comfort jekyll-assets has built-in support for some popular libraries.

Compass Support

Require jekyll-assets/compass to enable, e.g.:

require "jekyll-assets"
require "jekyll-assets/compass"

Now you can add @import "compass" in your SASS assets to get Compass goodies.

Note that if you want to use other than default Compass plugins/frameworks, you must require them BEFORE jekyll-assets/compass.

Bourbon Support

Require jekyll-assets/bourbon to enable, e.g.:

require "jekyll-assets"
require "jekyll-assets/bourbon"

Now you can add @import "bourbon" in your SASS assets to get Bourbon goodies.

The Directive Processor

Note: This section extracted from Sprockets README.

Sprockets runs the directive processor on each CSS and JavaScript source file. The directive processor scans for comment lines beginning with = in comment blocks at the top of the file.

//= require jquery
//= require jquery-ui
//= require backbone
//= require_tree .

The first word immediately following = specifies the directive name. Any words following the directive name are treated as arguments. Arguments may be placed in single or double quotes if they contain spaces, similar to commands in the Unix shell.

Note: Non-directive comment lines will be preserved in the final asset, but directive comments are stripped after processing. Sprockets will not look for directives in comment blocks that occur after the first line of code.

Supported Comment Types

The directive processor understands comment blocks in three formats:

/* Multi-line comment blocks (CSS, SCSS, JavaScript)
 *= require foo
 */

// Single-line comment blocks (SCSS, JavaScript)
//= require foo

# Single-line comment blocks (CoffeeScript)
#= require foo

Sprockets Directives

You can use the following directives to declare dependencies in asset source files.

For directives that take a path argument, you may specify either a logical path or a relative path. Relative paths begin with ./ and reference files relative to the location of the current file.

The require Directive

require path inserts the contents of the asset source file specified by path. If the file is required multiple times, it will appear in the bundle only once.

The include Directive

include path works like require, but inserts the contents of the specified source file even if it has already been included or required.

The require_directory Directive

require_directory path requires all source files of the same format in the directory specified by path. Files are required in alphabetical order.

The require_tree Directive

require_tree path works like require_directory, but operates recursively to require all files in all subdirectories of the directory specified by path.

The require_self Directive

require_self tells Sprockets to insert the body of the current source file before any subsequent require or include directives.

The depend_on Directive

depend_on path declares a dependency on the given path without including it in the bundle. This is useful when you need to expire an asset's cache in response to a change in another file.

The stub Directive

stub path allows dependency to be excluded from the asset bundle. The path must be a valid asset and may or may not already be part of the bundle. Once stubbed, it is blacklisted and can't be brought back by any other require.

Configuration

You can fine-tune configuration by editing your _config.yml:

#
# Plugin: jekyll-assets
#
assets:
  #
  # Pathname of the destination of generated (bundled) assets relative
  # to the destination of the root.
  #
  dirname: assets
  #
  # Base URL of assets paths.
  #
  baseurl: /assets/
  #
  # Pathnames where to find assets relative to the root of the site.
  #
  sources:
    - _assets/javascripts
    - _assets/stylesheets
    - _assets/images
  #
  # Sets compressors for the specific types of file: `js`, or `css`.
  # No compression by default.
  #
  # Possible variants:
  #
  #     css  => 'yui', 'sass', nil
  #     js   => 'yui', 'uglifier', nil
  #
  compress:
    js:   ~
    css:  ~
  #
  # Sets cachebusting policy for generated assets.
  #
  # Possible variants:
  #
  #   none - disables cachebusting
  #
  #     source file:  _assets/javascripts/app.css
  #     output file:  _site/assets/javascriptis/app.css
  #     output URL:   /assets/javascripts/app.css
  #
  #   soft - leave filenames as-is, but `?cb=<md5>` suffix for URLs generated
  #          with `asset_path`, `javascript` and `stylesheet`:
  #
  #     source file:  _assets/javascripts/app.css
  #     output file:  _site/assets/javascriptis/app.css
  #     output URL:   /assets/javascripts/app.css?cb=4f41243847da693a4f356c0486114bc6
  #
  #   hard - (default) injects cachebusting checksum into processed filename:
  #
  #     source file:  _assets/javascripts/app.css
  #     output file:  _site/assets/javascriptis/app-4f41243847da693a4f356c0486114bc6.css
  #     output URL:   /assets/javascripts/app-4f41243847da693a4f356c0486114bc6.css
  #
  cachebust: hard
  #
  # saves gzipped versions of the assets next to the un-compressed files
  #
  gzip: true

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

"Th-th-th-that's all folks!"

Feel free to follow me on twitter, chat via jabber or write an e-mail. :D

License

Copyright (C) 2012 Aleksey V Zapparov (http://ixti.net/)

The MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.