jekyll-assets 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c3f85683208d7c6a5e8212c0a26d86765fc44b4d
-  data.tar.gz: ab4ab48388c30fb14de9b49884ee89f700f04948
+  metadata.gz: 44d89fc0d1ca6db22209873e55c1672289e5e67f
+  data.tar.gz: 5a3e81f94ffcf988f713e2d971f931b30c5fd09f
 SHA512:
-  metadata.gz: '0619236826dae97812c7c9ad4e647b3ced92ac1eed4acf924fbe36163cb98270ef7a36aec3231b1bd21b1527efc4db31b8c14d8cedfb2bf564a49581c0d8a768'
-  data.tar.gz: a37c926b28a79d8e6be32d2067236fd63f34cb20d6bac7ff35935b8fe1387deec574cbf21254e70590db5ae37809134fdd834b5ef692335911a7879347481d52
+  metadata.gz: 45850b5a84a5cacfb3257789b39f0e3b5ff66c47f006c342c3fb4f5d71f465d9a8264c518f3a68005cbec2e452ac038387e75e21138c0d5452fcaba01ebb4fa8
+  data.tar.gz: 52ce19c278b2901eb63f12c0d5240294065a0c72a2711e1b5d8fe7a46d104abbfcf2f89bb4e1d6a476c2dc3d15544ca7379903421f118b3a3c492efae2ec33c9

data/Gemfile

@@ -1,26 +1,30 @@
+# Frozen-string-literal: true
+# Copyright: 2012 - 2017 - MIT License
+# Encoding: utf-8
+
 source "https://rubygems.org"
 gemspec
 
-gem "rake"
+gem "rake", require: false
 group :development do
-  gem "therubyracer", :platforms => :mri, :require => false
-  gem "therubyrhino", :platforms => :jruby, :require => false
-  gem "stackprof", :platforms => :mri, :require => false
-  gem "pry", :require => false
+  gem "mini_racer", require: false if RUBY_PLATFORM != "java"
+  gem "therubyrhino", require: false if RUBY_PLATFORM == "java"
+  gem "pry", require: false if RUBY_PLATFORM != "java"
 end
 
 group :test do
-  gem "codeclimate-test-reporter", :require => false
-  gem "rubocop", :require => false
+  gem "simplecov", require: false
+  gem "luna-rspec-formatters", require: false
+  gem "rubocop", require: false
 end
 
-gem "uglifier", :require => false
-gem "sprockets-es6", "~> 0.6", :require => false
-gem "autoprefixer-rails", "~> 7.0", :require => false
-gem "jekyll", "#{ENV["JEKYLL_VERSION"]}" if ENV["JEKYLL_VERSION"]
-gem "font-awesome-sass", "~> 4.4", :require => false
-gem "bootstrap-sass", "~> 3.3", :require => false
-gem "mini_magick", "~> 4.2", :require => false
-gem "image_optim", "~> 0.25", :require => false
-gem "image_optim_pack", "~> 0.5", :require => false
-gem "less", "~> 2.6.0", :require => false
+gem "uglifier", require: false
+gem "autoprefixer-rails", require: false
+gem "font-awesome-sass", "~> 4.4", require: false
+gem "sprockets", ENV["SPROCKETS_VERSION"] || "~> 4.0.beta", require: false
+gem "jekyll", ENV["JEKYLL_VERSION"], require: false if ENV["JEKYLL_VERSION"]
+gem "image_optim_pack", "~> 0.5", require: false
+gem "image_optim", "~> 0.25", require: false
+gem "mini_magick", "~> 4.2", require: false
+gem "babel-transpiler", require: false
+gem "bootstrap", require: false

data/LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2012 - 2015 Aleksey V Zapparov (http://ixti.net/)
-Copyright (c) 2015 - 2016 Jordon Bedwell (https://envygeeks.io)
+Copyright (c) 2015 - 2017 Jordon Bedwell (https://envygeeks.io)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,272 +1,289 @@
 <p align=center>
   <a href=https://goo.gl/BhrgjW>
-    <img src=https://envygeeks.io/badges/paypal-large_1.png alt=Donate>
+    <img src=https://envygeeks.io/badges/paypal-large_1.png>
   </a>
   <br>
-  <a href=https://travis-ci.org/jekyll/jekyll-assets>
-    <img src="https://travis-ci.org/jekyll/jekyll-assets.svg?branch=master" alt=Status>
+  <a href=https://travis-ci.org/envygeeks/jekyll-assets>
+    <img src="https://travis-ci.org/envygeeks/jekyll-assets.svg?branch=master">
+  </a>
+  <a href="https://codeclimate.com/github/envygeeks/jekyll-assets/test_coverage">
+    <img src="https://api.codeclimate.com/v1/badges/56f67324553069bf51e7/test_coverage" />
+  </a>
+  <a href="https://codeclimate.com/github/envygeeks/jekyll-assets/maintainability">
+    <img src="https://api.codeclimate.com/v1/badges/56f67324553069bf51e7/maintainability" />
   </a>
 </p>
 
+[1]:http://guides.rubyonrails.org/asset_pipeline.html
+[2]:https://github.com/rails/sprockets
+[3]:https://jekyllrb.com
+
+# Jekyll Assets 3.x
+
+***Jekyll Assets 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
+
+- [x] Jekyll like tag arguments.
+- [x] Support for `<img>` srcset.
+- [x] Proxies in `asset()` for SASS.
+- [x] Expanded source directories by default.
+- [x] Support for `srcset`, width, and density.
+- [x] Support for building HTML for external assets.
+- [x] Stripping of FrontMatter (`---`) before processing.
+- [x] Extensible/customizable decoupled HTML builders for tags.
+- [x] Support for `<audio>`, `<video>`, `<img>` discovery in Markdown.
+- [x] Responsive images with `srcset` `<picture>` tag support.
+- [x] Support for audio assets (using `assets` tag.)
+- [x] Support for video assets (using `assets` tag.)
+- [x] Easier proxies, with rolling proxies.
+- [x] Customizable HTML defaults.
+- [x] Configurable GZipping.
+- [x] Proxies via `<img>`.
+- [x] SourceMaps.
+
 # Jekyll Assets
 
-Jekyll assets is an asset pipeline using Sprockets 3 to build specifically for Jekyll. It utilizes new features of both Sprockets and Jekyll to try and achieve a clean and extensible assets platform.
+Jekyll Assets is a drop in [asset pipeline][1] that uses [Sprockets][2] to build specifically for Jekyll. It utilizes [Sprockets][2], and [Jekyll][3] 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][2], or [Jekyll][3], and your own source.  By default you can add Jekyll Assets to your Gemfile, as a plugin, and have it act as a drop-in replacement for Jekyll's basic SASS/CoffeeScript processors, with you only having to add it to your Gemfile, and updating your `<img>`, and `<link>`.
 
 ## Using Jekyll Assets with Jekyll
 
 ```ruby
-# Gemfile
-group :jekyll_plugins do
-  gem "jekyll-assets"
-end
+gem "jekyll-assets", group: :jekyll_plugins
+gem "jekyll-assets", git: "https://github.com/envygeeks/jekyll-assets", group: :jekyll_plugins
+gem "jekyll-assets", "~> x.x.alpha", group: :jekyll_plugins
 ```
 
-```yaml
-# _config.yml
-plugins:
-  - jekyll-assets
-```
+### Requirments
 
-## Configuration
+* Ruby ***2.3+***
+* Jekyll ***3.5+***
+* Sprockets ***3.3+***
 
-The configuration file is the same as Jekyll's, which is _config.yml. Use the special key "assets":
+***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.***
 
-```yaml
-assets:
-  compress:
-    css: false | true | default - development: false, production: true
-    js: false | true | default - development: false, production: true
-  autowrite: true
-  cache: false | directory | default: .asset-cache
-  cache_type: memory | filesystem | default: filesystem
-  cdn: https://cdn.example.com
-  skip_baseurl_with_cdn: false
-  skip_prefix_with_cdn: false
-  prefix: "/assets"
-  digest: true
-  assets:
-    - "*.png"
-    - "bundle.css"
-  sources:
-    - _assets/css
-    - _assets/images
-    - _assets/javascripts
-    - _assets/stylesheets
-    - _assets/fonts
-    - _assets/img
-    - _assets/js
-  features:
-    liquid: true | false | default: false
-    integrity: true | false | default: false
-    # This will add height and width attributes for an img tag.
-    automatic_img_size: true | false | n(fixnum): 2,4,6,8 | default: true
-    # This will add the digest path as an alt attribute for an img tag.
-    automatic_img_alt : true | false | default: true
+```ruby
+gem "sprockets", "~> 4.0.beta", {
+  require: false
+}
 ```
 
-### Liquid Processing with your Jekyll context
-
-By default (whether `features.liquid` is `true` or `false`) we will process
-all files with the extension `.liquid`, so if you give us `.scss.liquid`
-we will parse the liquid and then we will parse the SCSS and finally
-output your `.css` file. When `features.liquid` is set to `true`, we will process ***ALL*** files through Liquid, regardless of whether they have the `.liquid` extension. ***Use this at your own risk. As it can lead to some bugs, some bad output, and even some ugly edge cases... especially with things like Handlebars.***
-
-### Cache Folder
-
-If you plan to change the `cache` folder, please make sure to add that
-folder to your `exclude` list in Jekyll, or you will generate over and over
-and over again, `.` folders are not ignored by default as of Jekyll 3.x, so you should take heed of ignoring your own folders.
-
-### Sources
-
-The listed resources in the example are all defaults. It should be noted
-that we append your sources instead of replace our resources with yours. So
-if you add `_assets/folder` then we will append that to our sources and
-both will work. ***NOTE: if you use our `_assets` base folder container as a base folder for your Sprockets, we will not append our sources, we will only use that folder as the sole source (base folder.)***
-
-### Digesting
-
-* Disable digesting by default in development.
-* Digest by default in production.
-
-***You can force digesting with `digest: true` in your `_config.yml`***
-
-### Compression
-
-* Requires sass and uglifier.
-* Disable compression by default in development.
-* Enable by default in production.
-
-## Generating CSS with Jekyll Assets
+## Configuration
 
-The following section shows how to get started generating CSS using Jekyll
-Assets. It applies to a newly generated Jekyll site, however this should helpanyone who has a Jekyll site. It should also be applicable for other types of assets.
+The configuration file is the same as Jekyll's, which is `_config.yml`. Except we use the special key "assets" inside of that file.  Any environment variable noted as "val on `JEKYLL_ENV`" is only overridden when not explicitly set.  All values listed below are default, you need not copy these into your configuration file unless you plan to change a value.
 
-### Create the `_assets/css` directory
+```yaml
+digest: false
+source_maps: true # false on JEKYLL_ENV=production
+destination: "/assets"
+compression: true
+gzip: false
+defaults:
+   js: { integrity: false } # true on JEKYLL_ENV=production
+  css: { integrity: false } # true on JEKYLL_ENV=production
+  img: { integrity: false } # true on JEKYLL_ENV=production
+caching:
+  path: ".jekyll-cache/assets"
+  type: file # Possible values: memory, file
+  enabled: true
+precompile: []
+cdn:
+  baseurl: false
+  destination: false
+  url: null
+sources:
+- assets/css
+- assets/fonts
+- assets/images
+- assets/videos
+- assets/javascript
+- assets/video
+- assets/image
+- assets/img
+- assets/js
+- _assets/css
+- _assets/fonts
+- _assets/images
+- _assets/videos
+- _assets/javascript
+- _assets/video
+- _assets/image
+- _assets/img
+- _assets/js
+- css
+- fonts
+- images
+- videos
+- javascript
+- video
+- image
+- img
+- js
+plugins:
+  css: { autoprefixer: {}}
+  img: { optim: {}}
+```
 
-The default [Jekyll Assets configuration](#configuration) expects to find all the assets in directories under `_assets`. Create a directory for the CSS:
+## Tag
+### Usage
+#### Liquid
 
-```bash
-mkdir -p _assets/css
+```liquid
+{% asset src @magick:2x alt='This is my alt' %}
+{% asset src @magick:2x alt='This is my alt' %}
 ```
 
-### Move the CSS files to the new `_assets/css` directory
+#### HTML
 
-Jekyll comes with a `css` directory containing a `main.css` file and then a `_sass` directory with a few Sass imports. Move all of that to the `_assets/css` directory.
-
-```bash
-mv css/main.css _assets/css
-mv _sass/* _assets/css
+```html
+<img src="src" asset="@magick:2x" alt="This is my alt">
+<img src="src" alt="This is my alt" asset>
 ```
 
-### Remove Jekyll front matter
-
-Jekyll includes some empty [front matter](https://jekyllrb.com/docs/frontmatter/) in `main.css`. Remove that as Sprockets will not understand it.
+### Defaults
 
-### Update the layout
+We provide several defaults that get set when you run an asset, depending on content type, this could be anything from type, all the way to integrity.  If there is a default attribute you do not wish to be included, you can disable the attribute with `!attribute`, and it will be skipped over.
 
-The layout will no longer be pointing to the correct `main.css` file. Jekyll Assets supplies [liquid tags](#tags) to generate the correct HTML for these assets. Open `_includes/head.html` and replace the `<link>` to the CSS with:
+#### Usage
 
 ```liquid
-{% css main %}
+{% asset img.png !integrity %}
+{% asset bundle.css !type   %}
 ```
 
-Start up your local Jekyll server and if everything is correct, your site will be serving CSS via Sprockets. Read on for more information on how to customize your Jekyll Assets setup.
+### Arguments
 
-## Addons
+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.
 
-* Font Awesome `gem "font-awesome-sass"`
+#### Builtins
 
-  ```scss
-    @import 'font-awesome-sprockets'
-    @import 'font-awesome'
-  ```
+| Arg | Description | Type | Return Type |
+|---|---|---|---|
+| `@path` | Path | `*/*` | `text`
+| `@data` | `data` URI | `*/*` | `text` |
+| `@inline` | CSS `<style>` | `text/css` | `text/html` |
+| | `text/svg+xml` XML | `image/svg+xml` | `text/svg+xml` |
+| | JavaScript `<script>` | `application/javascript` | `text/html` |
+| | Image `<img>` | `image/*` | `text/html` |
+| `srcset` | [Responsive]() `<img>` | `image/*` | `text/html` |
+| `srcset` + `@pic` | [Responsive]() `<pic>` | `image/*` | `text/html` |
 
-* CSS Auto-Prefixing `gem "autoprefixer-rails"`
+***Jekyll Assets uses [@envygeeks](https://github.com/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`](https://github.com/envygeeks/liquid-tag-parser)***
 
-    ```yml
-    assets:
-      autoprefixer:
-        browsers:
-          - "last 2 versions"
-          - "IE > 9"
-    ```
+#### Responsive Images
 
-* Bootstrap `gem "bootstrap-sass"`
+Jekyll Assets has the concept of responsive images, using the `picture` (when using `@pic` w/ `srcset`) and the `<img>` tag when using `srcset`. If you ship multiple `srcset` with your image, we will proxy, build and then ship out a `picture/img` tag with any number of `source/srcset`, and in the case of picture, with the original image being the `image`.
 
-  ```scss
-    @import 'bootstrap-sprockets'
-    @import 'bootstrap'
-  ```
+##### `<picture>` usage, requires `@pic`
+###### Example
 
-* ES6 `gem "sprockets-es6"`
-* Image Magick `gem "mini_magick"`
-* ImageOptim `gem "image_optim"`
-
-  ```yml
-  assets:
-    image_optim:
-      default:
-        verbose: true
-      zero_png:
-        advpng:
-          level: 0
-        optipng:
-          level: 0
-        pngout:
-          strategy: 4
-  ```
-
-  Check the [ImageOptim docs](https://github.com/toy/image_optim#configuration) to get idea about configuration options.
+```liquid
+{% asset img.png @pic
+    srcset:max-width="800 2x"
+    srcset:max-width="600 1.5x"
+    srcset:max-width="400 1x"
+      %}
+```
 
-* LESS `gem "less"`
+```html
+<picture>
+  <source srcset="1.png 2x"   media="(max-width:800px)">
+  <source srcset="2.png 1.5x" media="(max-width:600px)">
+  <source srcset="3.png 1x"   media="(max-width:400px)">
+  <img src="img.png">
+</picture>
+```
 
-## Bower
+##### `<img>` usage
+###### Example
 
-Modify your `.bowerrc` file and add:
+```liquid
+{% asset img.png
+    srcset:width="400 2x"
+    srcset:width="600 1.5x"
+    srcset:width="800 1x"
+      %}
+
+{% asset img.png
+    srcset:width=400
+    srcset:width=600
+    srcset:width=800
+      %}
+```
 
-```json
-{
-  "directory": "_assets/bower"
-}
+```html
+<img srcset="1.png   2x, 2.png 1.5x, 3.png   1x">
+<img srcset="1.png 400w, 2.png 600w, 3.pnx 800w">
 ```
 
-And then add `_assets/bower` to your sources list and Sprockets will do the
-the rest for you... you can even `//= require bower_asset.js`. We will even
-compress them for you per normal if Sprockets supports it and allows us to.
+##### Args
+
+| Arg | Type | Description | `@pic` Only |
+| --- | ---- | ------------| ----------- |
+| `width`     | Width [Density] | Resize, set `srcset="<Src> <<Width>px/Density>"` | ✗ |
+| `min-width` | Width [Density] | Resize, set `media="(min-width: <Width>px)"` | ✔ |
+| `max-width` | Width [Density] | Resize, set `media="(max-width: <Width>px)"` | ✔ |
+| `sizes`     | Any | Your value, unaltered, unparsed. | ✗ |
+| `media`     | Any | Your value, unaltered, unparsed. | ✗ |
 
-***You do not need to modify your `.bowerrc` file, you can optionally just
-add it to your sources list and it will work that way too! As long as it's in
-your Jekyll folder.***
+***If you set `media`, w/ `max-width`, `min-width`, we will not ship `media`, we will simply resize and assume you know what you're doing.  Our parser is not complex, and does not make a whole lot of assumptions on your behalf, it's simple and only meant to make your life easier.  In the future we may make it more advanced.***
 
-## Tags
+## Liquid
 
-* image, img
-* javascript, js
-* stylesheet, css, style
-* asset, asset_source
-* asset_path
+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.
 
-### Tag Example:
+### Usage
 
 ```liquid
-{% img src magick:2x alt:'This is my alt' %}
-{% img src magick:2x alt:'This is my alt' sprockets:accept:image/gif %}
+{% img '{{ image_path }}' %}
+{% img '{{ image_path }}' proxy:key='{{ value }}' %}
+{% img {{\ image_path\ }} %}
 ```
 
-### What do the colons mean? Proxies/Tags
+#### `.liquid.ext`, and `.ext.liquid`
 
-* `argument` is a boolean HTML argument.
-* `key:value` is an HTML key="value" if no proxy exists.
-* `proxy:key:value` will set a proxy key with the given value.
-* `proxy:key` is a boolean argument if the proxy and key exists.
-* `unknown:key:value` will raise `DoubleColonError`, escape it.
-* `proxy:unknown:value` will raise a `UnknownProxyError`.
+```scss
+.bg {
+  background: url(asset_path("{{ site.background_image }}"));
+}
+```
 
-Lets say we have `sprockets` proxies and sprockets allows you to proxy accept,
-if you send `{% img src sprockets:accept:image/gif }` then Sprockets find_asset
-will get `{ :accept => "image/gif" }` but if you try to proxy "unknown" on
-sprockets we will raise a Proxy error. For more information then look at
-`parser_spec.rb` in the spec folder because it literally lays out the ground
-rules for our tags as a specification.
+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/JavaScript since we pre-process your text files. ***On Sprockets 4.x you can use `.liquid.ext` and `.ext.liquid`, but because of the way Sprockets 3.x works, we have opted to only allow the default extension of `.ext.liquid` when running on "Old Sprockets" (AKA 3.x.)  If you would like Syntax + Liquid you should opt to install Sprockets 4.x so you can get the more advanced features.***
 
-### Current Proxies:
+##### Importing
 
-* `sprockets:accept:<value>`
-* `sprockets:write_to:<value>`
+***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.***
 
-## Liquid Variables
+## Sass/SCSS Helpers
 
-We support liquid arguments for tag values (but not tag keys), and we also
-support Liquid pre-processing (with your Jekyll context) sass/less/css files
-you need do nothing special for the preprocessing an entire file, it's
-always done.
+We provide two helpers, `asset_path` to return the path of an asset, and `asset_url` which will wrap `asset_path` into a `url()` for you, making it easy for you to extract your assets and their paths inside of SCSS.
 
-An example of using Liquid in your tags:
+### Usage
 
-```liquid
-{% img '{{ image_path }}' %}
-{% img '{{ image_path }}' proxy:key:'{{ value }}' %}
-{% img {{\ image_path\ }} %}
+```scss
+body {
+  background-image: asset_url("img.png");
+}
 ```
 
-An example of using Liquid in your SCSS:
+#### Proxies, and Other Arguments
+
+Any argument that is supported by our regular tags, is also supported by our Sass/SCSS helpers, with a few obvious exceptions (like `srcset`).  This means that you can wrap your assets into `magick` if you wish, or `imageoptim` or any other proxy that is able to spit out a path for you to use.
+
+##### Usage
 
 ```scss
-.bg {
-  background: url(asset_path("{{ site.background_image }}"));
+body {
+  background-image: asset_url("img.png @magick:half")
 }
 ```
 
-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.
+***Not we do not validate your arguments, so if you send a conflicting argument that results in invalid CSS, you are responsible for that, in that if you ship us `srcset` we won't throw, we will spit out HTML for you, and it will break your CSS, this is by design.***
 
-## Getting a list of your assets and basic info from Liquid
+## 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.
+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.
 
 ```liquid
 {{ assets["bundle.css"].content_type }} => "text/css"
@@ -276,154 +293,205 @@ info that we wish you to have access to without having to prepare the class.
 
 The current list of available accessors:
 
-* `logical_path`
-* `content_type` -> `type`
-* `filename`
-* `basename`
-* `width`
-* `height`
-* `digest_path`
+| 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 |
 
-If you would like more, please feel free to add a pull request, at this
-time we will reject all pull requests that wish to add any digested paths as
-those are dynamically created when a proxy is ran so we can never predict
-it reliably unless we proxy and that would be a performance problem.
+### Looping
 
-### Dynamically loading assets
+```liquid
+{% for k,v in assets %}
+  {{ k }}
+{% endfor %}
+```
+
+### Dynamic
 
 Using Liquid Drop `assets`, you can check whether an asset is present.
 
 ```liquid
-{% if assets[page.image] %}
-  {% img '{{ page.image }}' %}
+{% if assets[page.image] %}{% img '{{ page.image }}' %}
 {% else %}
-  {% img 'default.jpg' %}
+  {% img default.jpg %}
 {% endif %}
 ```
 
-## ERB Support
-
-ERB Support is removed in favor of trying to get this included on Github Pages
-eventually (if I can.) Having ERB presents a security risk to Github because it
-would allow you to use Ruby in ways they don't want you to.
-
-## Filters
-
-There is a full suite of filters, actually, any tag and any proxy can be a
-filter by way of filter arguments, take the following example:
+## Filter
 
 ```liquid
-{{ src | img : "magick:2x magick:quality:92" }}
+{{ src | asset:"@magick:2x magick:quality:92" }}
 ```
 
-### Jekyll Assets Multi
+## Hooks
 
-Jekyll Assets has a special called `jekyll_asset_multi` which is meant to be used for things like the header, where it would be nice to be able to include multiple assets at once.  You can use it like so:
+| Point | Name | Instance | Args |
+|---|---|---|---|
+| `:env` | `:before_init` | ✔ | ✗ |
+| `:env` | `:after_init` | ✔ | ✗ |
+| `:config` | `:before_merge` | ✗ | `Config{}` |
+| `asset` | `:before_compile` | ✗ | `Asset`, `Manifest` |
 
-```liquid
-{{ 'css:bundle.css "js:bundle.js async:true"' | jekyll_asset_multi }}
+### Usage
+
+```ruby
+Jekyll::Assets::Hook.register :env, :before_init do
+  append_path "myPluginsCustomPath"
+end
 ```
 
-## Hooks
+```ruby
+Jekyll::Assets::Hook.register :config, :init do |c|
+  c.deep_merge!({
+    plugins: {
+      my_plugin: {
+        opt: true
+      }
+    }
+  })
+end
+```
 
-* `:env => [:init]`
+#### Plugin Hooks
 
-You can register and trigger hooks like so:
+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
+
+```ruby
+Jekyll::Assets::Hook.add_point(:plugin, :hook)
+```
 
 ```ruby
-Jekyll::Assets::Hook.register :env, :init do
-  # Your Work
+Jekyll::Assets::Hook.trigger(:plugin, :hook)  { |v| v.call(:arg) }
+Jekyll::Assets::Hook.trigger(:plugin, :hook) do |v|
+  instance_eval(&v)
 end
 ```
 
-## Combining Multiple Scripts / Stylesheets
+## Default Plugins
+### Font Awesome
+#### Installation
 
-To minimize the number of HTTP requests, combine stylesheets and scripts into one file.
+```ruby
+gem "font-awesome-sass"
+```
 
-### SCSS
+#### Usage
 
-Use the `@import` statement. Given a list of files in `_assets/css`:
+```scss
+@import "font-awesome-sprockets"
+@import "font-awesome"
+```
+
+### CSS Auto-Prefixing
+#### Installation
+
+```ruby
+gem "autoprefixer-rails"
+```
+
+#### Config
 
-- `main.scss`
-- `_responsive.scss`
-- `_fonts.scss`
+```yml
+assets:
+  autoprefixer:
+    browsers:
+    - "last 2 versions"
+    - "IE > 9"
+```
+
+### Bootstrap
+#### Installation
+
+```ruby
+gem "bootstrap-sass"
+```
 
-...have this in your `main.scss`:
+#### Usage
 
 ```scss
-@import 'responsive';
-@import 'fonts';
-// ...
+@import 'bootstrap'
 ```
 
-Include the `main` stylesheet in your HTML: `{% css main %}`.
+### ImageMagick
+#### Installation
 
-### JavaScript
+```ruby
+gem "mini_magick"
+```
+
+#### Tag Args
 
-Use `//= require` to import and bundle component scripts into one file. More from [#241](https://github.com/jekyll/jekyll-assets/issues/241).
+See the [MiniMagick docs](https://github.com/minimagick/minimagick#usage)
+to get an idea what `<value>` can be.
 
-Given a list of files in `_assets/js`:
+| Name | Accepts Value |
+|---|---|
+| `magick:compress` | ✔ |
+| `magick:resize` | ✔ |
+| `magick:format`<sup>*</sup> | ✔ |
+| `magick:quality` | ✔ |
+| `magick:rotate` | ✔ |
+| `magick:gravity` | ✔ |
+| `magick:crop` | ✔ |
+| `magick:flip` | ✔ |
+| `@magick:double` | ✗ |
+| `@magick:half` | ✗ |
 
-- `main.js`
-- `jquery.js`
+<sup>\*</sup> ***`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.***
 
-...have this in your `main.js`:
+### ImageOptim
+#### Installation
 
-```js
-//= require jquery
-// ...
+```ruby
+gem "image_optim"
 ```
 
-Include the `main` script in your HTML: `{% js main %}`.
+#### Config
 
-## Sass Helpers
+  Check the [ImageOptim](https://github.com/toy/image_optim#configuration) to get idea about configuration options.
 
-***Our currently supported helpers are:***
+```yml
+assets:
+  plugins:
+    img:
+      optim:
+        default:
+          verbose: true
+        zero_png:
+          advpng:
+            level: 0
+          optipng:
+            level: 0
+          pngout:
+            strategy: 4
+```
 
-* asset_url
-* asset_path
-* image_path
-* font_path
-* image_url
-* font_url
+#### Tag Args
 
-### Image Magick Proxy arguments:
+| Name | Accepts Value |
+|---|---|
+| `@image_optim:preset`<sup>*</sup> | ✗ |
 
-**NOTE: You'll need the `mini_magick` gem installed for these to work**
-To install `mini_magick`, add `gem "mini_magick"` to your `Gemfile`
+<sup>\*</sup>***Where `preset` is the name of the preset.***
 
-See the [MiniMagick docs](https://github.com/minimagick/minimagick#usage)
-to get an idea what `<value>` can be.
+### 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
 
-* `magick:resize:<value>`
-* `magick:format:<value>`
-* `magick:quality:<value>`
-* `magick:rotate:<value>`
-* `magick:gravity:<value>`
-* `magick:crop:<value>`
-* `magick:flip:<value>`
-* `magick:quadruple`, `magick:4x`
-* `magick:one-third`, `magick:1/3`
-* `magick:three-fourths`, `magick:3/4`
-* `magick:two-fourths`, `magick:2/4`
-* `magick:two-thirds`, `magick:2/3`
-* `magick:one-fourth`, `magick:1/4`
-* `magick:half`, `magick:1/2`
-
-### ImageOptim Proxy arguments:
-
-**NOTE: You'll need the `image_optim` gem installed for these to work**
-To install `image_optim`, add `gem "image_optim"` to your `Gemfile`
-
-See the [ImageOptim docs](https://github.com/toy/image_optim#gem-installation) to ensure proper dependencies installation.
-
-* `image_optim:default` same as `image_optim:preset:default`
-* `image_optim:preset:<name>`
-
-## Having trouble with our documentation?
-
-If you do not understand something in our documentation please feel
-free to file a ticket and it will be explained and the documentation updated,
-however... if you have already figured out the problem please feel free to
-submit a pull request with clarification in the documentation and we'll
-happily work with you on updating it.
+| Name | Class | Type |
+|---|---|---|
+| `@doc` | `Nokogiri:: XML::Document` | `image/svg+xml` |
+| `@doc` | `Nokogiri::HTML::Document` | `image/*` |