Powerful asset pipeline for Jekyll that collects, converts and compresses JavaScript and CSS assets
Powerful asset pipeline for Jekyll that collects, converts and compresses JavaScript and CSS assets
This project has moved.
- Active development now lives at https://github.com/janosrusiczki/jekyll-asset-pipeline.
- The gem on RubyGems is unchanged -
gem install jekyll_asset_pipelineworks the same.- Please open issues and PRs at the new repo.
- The reason for the move was that this project was still on Travis which is long defunct and Matt's Github account was not configured to handle Github Action builds.
Jekyll Asset Pipeline is a powerful asset pipeline that automatically collects, converts and compresses / minifies your site's JavaScript and CSS assets when you compile your Jekyll site.
link and script tags that point to bundled assetsJekyll Asset Pipeline's workflow can be summarized as follows:
css_asset_tag and javascript_asset_tag Liquid tags. Each occurrence of either of these tags identifies when a new bundle needs to be created and outlines (via a manifest) which assets to include in the bundle._site output folder.css_asset_tag and javascript_asset_tag Liquid tags with HTML link and script tags, respectively, that link to the finished bundles.Jekyll Asset Pipeline is extremely easy to add to your Jekyll project and has no incremental dependencies beyond those required by Jekyll. Once you have a basic Jekyll site up and running, follow the steps below to install and configure Jekyll Asset Pipeline.
jekyll_asset_pipeline gem via Rubygems.$ gem install jekyll_asset_pipeline If you are using Bundler to manage your project's gems, you can just add jekyll_asset_pipeline to your Gemfile and run bundle install.
_plugins folder to your project if you do not already have one. Within the _plugins folder, add a file named jekyll_asset_pipeline.rb with the following require statement as its contents.require 'jekyll_asset_pipeline'Move your assets into a Jekyll ignored folder (i.e. a folder that begins with an underscore _) so that Jekyll won't include these raw assets in the site output. It is recommended to use an _assets folder to hold your site's assets.
Add the following Liquid blocks to your site's HTML head section. These blocks will be converted into HTML link and script tags that point to bundled assets. Within each block is a manifest of assets to include in the bundle. Assets are included in the same order that they are listed in the manifest. Replace the foo and bar assets with your site's assets. At this point we are just using plain old javascript and css files (hence the .js and .css extensions). See the Asset Preprocessing section to learn how to include files that must be preprocessed (e.g. CoffeeScript, Sass, Less, Erb, etc.). Name the bundle by including a string after the opening tag. We've named our bundles "global" in the below example.
{% css_asset_tag global %}
- /_assets/foo.css
- /_assets/bar.css
{% endcss_asset_tag %}
{% javascript_asset_tag global %}
- /_assets/foo.js
- /_assets/bar.js
{% endjavascript_asset_tag %}Asset manifests must be formatted as YAML arrays and include full paths to each asset from the root of the project. YAML does not allow tabbed markup, so you must use spaces when indenting your YAML manifest or you will get an error when you compile your site. If you are using assets that must be preprocessed, you should append the appropriate extension (e.g. '.js.coffee', '.css.less') as discussed in the Asset Preprocessing section.
jekyll build command to compile your site. You should see an output that includes the following Jekyll Asset Pipeline status messages.$ jekyll build
Generating...
Asset Pipeline: Processing 'css_asset_tag' manifest 'global'
Asset Pipeline: Saved 'global-md5hash.css' to 'yoursitepath/assets'
Asset Pipeline: Processing 'javascript_asset_tag' manifest 'global'
Asset Pipeline: Saved 'global-md5hash.js' to 'yoursitepath/assets' If you do not see these messages, check that you have not set Jekyll's safe option to true in your site's _config.yml. If the safe option is set to true, Jekyll will not run plugins.
That is it! You should now have bundled assets. Look in the _site folder of your project for an assets folder that contains the bundled assets. HTML tags that point to these assets have been placed in the HTML output where you included the Liquid blocks. You may notice that your assets have not been converted or compressed-- we will add that functionality next.
Asset preprocessing (i.e. conversion) allows us to write our assets in languages such as CoffeeScript, Sass, Less, Erb or any other language. One of Jekyll Asset Pipeline's key strengths is that it works with any preprocessing library that has a ruby wrapper. Adding a preprocessor is straightforward, but requires a small amount of additional code.
In the following example, we will add a preprocessor that converts CoffeeScript into JavaScript.
jekyll_asset_pipeline.rb file that we created in the Getting Started section, add the following code to the end of the file (i.e. after the require statement).module JekyllAssetPipeline
class CoffeeScriptConverter < JekyllAssetPipeline::Converter
require 'coffee-script'
def self.filetype
'.coffee'
end
def convert
return CoffeeScript.compile(@content)
end
end
end The above code adds a CoffeeScript converter. You can name a converter anything as long as it inherits from JekyllAssetPipeline::Converter. The self.filetype method defines the type of asset a converter will process (e.g. .coffee for CoffeeScript) based on the extension of the raw asset file. A @content instance variable that contains the raw content of our asset is made available within the converter. The converter should process this content and return the processed content (as a string) via a convert method.
coffee-script gem.$ gem install coffee-script If you are using Bundler to manage your project's gems, you can just add coffee-script to your Gemfile and run bundle install.
Append a .coffee extension to the filename of any asset that should be converted with the CoffeeScriptConverter. For example, foo.js would become foo.js.coffee.
Run the jekyll build command to compile your site.
That is it! Your asset pipeline has converted any CoffeeScript assets into JavaScript before adding them to a bundle.
You probably get the gist of how converters work, but here's an example of a SASS converter for quick reference.
module JekyllAssetPipeline
class SassConverter < JekyllAssetPipeline::Converter
require 'sass'
def self.filetype
'.scss'
end
def convert
return Sass::Engine.new(@content, syntax: :scss).render
end
end
endDon't forget to install the sass gem or add it to your Gemfile and run bundle install before you run the jekyll build command since the above SASS converter requires the sass library as a dependency.
If you're using @import statements in your SASS files, you'll probably need to specify a base load path to the SASS engine in your convert method.
You can use the @dirname instance variable for this, which contains the path to the current asset's directory:
...
def convert
return Sass::Engine.new(@content, syntax: :scss, load_paths: [@dirname]).render
end
...module JekyllAssetPipeline
class LessConverter < JekyllAssetPipeline::Converter
require 'less'
def self.filetype
'.less'
end
def convert
return Less::Parser.new.parse(@content).to_css
end
end
endDon't forget to install the less gem or add it to your Gemfile and run bundle install before you run the jekyll build command since the above LESS converter requires the less library as a dependency.
As with the SASS convertor, you'll probably need to specify a base load path and pass that to the LESS Parser:
...
def convert
return Less::Parser.new(paths: [@dirname]).parse(@content).to_css
end
...If you would like to run an asset through multiple preprocessors successively, you can do so by naming your assets with nested file extensions. Nest the extensions in the order (right to left) that the asset should be processed. For example, .css.scss.erb would first be processed by an erb preprocessor then by a scss preprocessor before being rendered. This convention is very similar to the convention used by the Ruby on Rails asset pipeline.
Don't forget to define preprocessors for the extensions you use in your filenames, otherwise Jekyll Asset Pipeline will not process your asset.
Asset compression allows us to decrease the size of our assets and increase the speed of our site. One of Jekyll Asset Pipeline's key strengths is that it works with any compression library that has a ruby wrapper. Adding asset compression is straightforward, but requires a small amount of additional code.
In the following example, we will add a compressor that uses Yahoo's YUI Compressor to compress our CSS and JavaScript assets.
jekyll_asset_pipeline.rb file that we created in the Getting Started section, add the following code to the end of the file (i.e. after the require statement).No open issues yet, or sync has not completed.