Skip to content

Latest commit

 

History

History
397 lines (307 loc) · 10.1 KB

README.md

File metadata and controls

397 lines (307 loc) · 10.1 KB


Status

Jekyll Assets 3.x

Jekyll 3.x is currently unreleased. It is scheduled to released sometime in October. If you are looking for documentation, for the current release (2.x) please see: https://github.com/jekyll/jekyll-assets/tree/2.4-legacy it should have what you are looking for.

What's new

  • Jekyll like tag arguments.
  • Proxies in asset() for SASS.
  • Expanded source directories by default.
  • Support for srcset, width, and density.
  • Stripping of FrontMatter (---) before processing.
  • Extensible/customizable decoupled HTML builders for tags.
  • Support for <audio>, <video>, <img> discovery in Markdown.
  • Responsive images with srcset <picture> tag support.
  • Support for audio assets (using assets tag.)
  • Support for video assets (using assets tag.)
  • Easier proxies, with rolling proxies.
  • Customizable HTML defaults.
  • Configurable GZipping.
  • Proxies via <img>.
  • SourceMaps.

Jekyll Assets

Jekyll assets is an asset pipeline that uses Sprockets to build specifically for Jekyll. It utilizes Sprockets, and Jekyll to try and achieve a clean and extensible assets platform that supports plugins, caching, converting your assets, and even the proxy of said assets in a way that does not interfere with either Sprockets, or Jekyll, and your own source.

Using Jekyll Assets with Jekyll

# Gemfile
gem "jekyll-assets", {
  group: :jekyll_plugins
}

Requirments

  • Ruby 2.3+
  • Jekyll 3.5+
  • Sprockets 3.3+

If you would like SourceMap support, or faster Sprockets, you should prefer to use Sprockets "~> 4.0.beta", we support SourceMaps in this version of Sprockets because it supports them. It's manifest an other features are also much better inside of this version of Sprockets.

Configuration

The configuration file is the same as Jekyll's, which is _config.yml. Except we use the special key "assets" inside of that file.

liquid: false
prefix: "/assets"
integrity: false
autowrite: true
digest: false
strict: false
caching:
  enabled: true
  path: ".jekyll-cache/assets"
  type: file
precompile: []
cdn:
  baseurl: false
  prefix: false
plugins:
  img:
    optim: {}
  compression:
    js:
      enabled: false
      opts: {}
    css:
      enabled: true
sources:
- assets/css
- assets/fonts
- assets/images
- assets/javascript
- assets/image
- assets/img
- assets/js

- _assets/css
- _assets/fonts
- _assets/images
- _assets/javascript
- _assets/image
- _assets/img
- _assets/js

- css
- fonts
- images
- javascript
- image
- img
- js

Tag

Usage

{% asset src @magick:2x alt='This is my alt' %}
{% asset src @magick:2x alt='This is my alt' %}

Arguments

Our tags will take any number of arguments, and convert them to HTML, and even attach them to your output if the HTML processor you use accepts that kind of data. This applies to anything but hashes, and arrays. So adding say, a class, or id, is as easy as doing id="val" inside of your tag arguments.

Builtins

Arg Description Type Return Type
@path Path Any text
@uri Data URI Any text
@source Source Any text
@data Data URI <img> image/* text/html
@inline text/svg+xml XML Data image/svg+xml text/svg+xml
@inline JavaScript <script> application/javascript text/html
@inline CSS <style> text/css text/html
srcset Responsive Args text/html

Jekyll Assets uses @envygeeks liquid-tag-parser which supports advanced arguments (hash based arguments) as well as array based arguments. When you see something like k1:sk1=val it will get converted to k1 = { sk1: "val" } in Ruby. To find out more about how we process tags you should visit the documentation for liquid-tag-parser

Responsive Images

Jekyll Assets has the concept of responsive images, using the picture tag, if you ship multiple srcset with your image, we will proxy, build and then ship out a picture tag with any number of source and the original image being the image.

Usage
{% asset img.svg srcset='magick:format=image/png magick:resize=400 media="(min-width:400px)"'
                 srcset='magick:format=image/png magick:resize=600 media="(min-width:600px)"'
                 srcset='magick:format=image/png magick:resize=800 media="(min-width:800px)"' %}

Liquid

We support liquid arguments for tag values (but not tag keys), and we also support Liquid pre-processing (with your Jekyll context) of most files if they end with .liquid. This will also give you access to our filters as well as their filters, and Jekyll's filters.

Usage

{% img '{{ image_path }}' %}
{% img '{{ image_path }}' proxy:key='{{ value }}' %}
{% img {{\ image_path\ }} %}

.liquid

.bg {
  background: url(asset_path("{{ site.background_image }}"));
}

You have full access to your entire Jekyll context from any liquid processing we do, so you can do whatever you like and be as dynamic as you like, including full loops and conditional Liquid based CSS since we pre-process your text files.

Importing

In order to import your Liquid pre-processed assets inside of Liquid or JS you should use a Sprockets //require=, Sprockets does not integrate that deeply into JavaScript and SASS to allow you to @import and pre-process.

List

We provide all your assets as a hash of Liquid Drops so you can get basic info that we wish you to have access to without having to prepare the class.

{{ assets["bundle.css"].content_type }} => "text/css"
{{ assets["images.jpg"].width  }} => 62
{{ assets["images.jpg"].height }} => 62

The current list of available accessors:

Method Description
content_type The RFC content type
height The asset height (if available)
filename The full path to the assets actual file
width The asset width (if available)
digest_path The prefixed path

Looping

{% for k,v in assets %}
  {{ k }}
{% endfor %}

Dynamic

Using Liquid Drop assets, you can check whether an asset is present.

{% if assets[page.image] %}{% img '{{ page.image }}' %}
{% else %}
  {% img default.jpg %}
{% endif %}

Filter

{{ src | asset:"@magick:2x magick:quality:92" }}

Hooks

Point Name Instance Args
:env :init ✔ ✗
:config :init ✗ Config{}
asset :compile ✗ Asset, Manifest

Usage

Jekyll::Assets::Hook.register :env, :init do
  append_path "myPluginsCustomPath"
end
Jekyll::Assets::Hook.register :config, :init do |c|
  c.deep_merge!({
    plugins: {
      my_plugin: {
        opt: true
      }
    }
  })
end

Plugin Hooks

Your plugin can also register it's own hooks on our Hook system, so that you can trigger hooks around your stuff as well, this is useful for extensive plugins that want more power.

Usage
Jekyll::Assets::Hook.add_point(:plugin, :hook)
Jekyll::Assets::Hook.trigger(:plugin, :hook)  { |v| v.call(:arg) }
Jekyll::Assets::Hook.trigger(:plugin, :hook) do |v|
  instance_eval(&v)
end

Default Plugins

Font Awesome

Installation

gem "font-awesome-sass"

Usage

@import "font-awesome-sprockets"
@import "font-awesome"

CSS Auto-Prefixing

Installation

gem "autoprefixer-rails"

Config

assets:
  autoprefixer:
    browsers:
    - "last 2 versions"
    - "IE > 9"

Bootstrap

Installation

gem "bootstrap-sass"

Usage

@import 'bootstrap'

ImageMagick

Installation

gem "mini_magick"

Tag Args

See the MiniMagick docs to get an idea what <value> can be.

Name Accepts Value
magick:compress ✔
magick:resize ✔
magick:format* ✔
magick:quality ✔
magick:rotate ✔
magick:gravity ✔
magick:crop ✔
magick:flip ✔
@magick:double ✗
@magick:half ✗

* magick:format requires an ext or a valid MIME content type like image/jpeg or .jpg. We will ImageMagick -format on your behalf with that information by getting the extension.

ImageOptim

Installation

gem "image_optim"

Config

Check the ImageOptim to get idea about configuration options.

assets:
  plugins:
    img:
      optim:
        default:
          verbose: true
        zero_png:
          advpng:
            level: 0
          optipng:
            level: 0
          pngout:
            strategy: 4

Tag Args

Name Accepts Value
@image_optim:preset* ✗

*Where preset is the name of the preset.

Building Your Own Plugins

Global Instance Vars

Name Class
@env Jekyll::Assets::Env
@args Liquid::Tag::Parser{}
@jekyll Jekyll::Site
@asset Sprockets::Asset
HTML Instance Vars
Name Class Type
@doc Nokogiri:: XML::Document image/svg+xml
@doc Nokogiri::HTML::Document image/*