spress-plugin spress-plugin-assets

shdev/spress-plugin-assets

It allows to asset boost your Spress site

Assets plugin for Spress

, _(*1)

This plugin has the aim to bring the most features of jekyll-assets to SPRESS., _(*2)

**This plugin requires Spress >= 2.2., _(*3)

How to install?

Go to your site folder and input the following command:, _(*4)

$ spress add:plugin shdev/spress-plugin-assets

As as soft dependency you need ImageMagick, _(*5)

Under macOS I used Homebrew to install it with, _(*6)

$ brew install imagemagick

How to use?

Store your assets in src/assets with your folder structure, _(*7)

For example this structure, _(*8)

./src/assets/
|- img
   |- header.jpg
   |- feature-image.jpg
|- css
   |- style.css
|- js
   |- app.js

In config.yml you can set the following options. Here the default values are displayed., _(*9)

asset_output_path: 'build/assets'
asset_output_web_prefix: '/assets'
asset_defaults_gravity: 'Center'
asset_defaults_quality: ~

asset_output_path the path where the file is stored during building., _(*10)

asset_output_web_prefix is the path prefix for the link., _(*11)

asset_defaults_gravity is the default gravity for cropping a image if nothing is given in asset-filter options, _(*12)

asset_defaults_quality is the default quality for images. I would recommend 90. If this is null imagemagick is not necessary as dependency., _(*13)

For example if you use a CDN you want the assets in an own build-folder and the URL prefix contains information about your CDN., _(*14)

In your template you use the path relative to src/assets for your items with the asset filters., _(*15)

Filter asset_path

This filter gives the path of, _(*16)

{{ 'img/header.jpg' | asset_path }}

Renders the URL, _(*17)

<asset_output_web_prefix>/img/header_813dec0e6ec1420d101c3f07bfc0a135.jpg

and writes the file, _(*18)

<asset_output_path>/img/header_813dec0e6ec1420d101c3f07bfc0a135.jpg

You see the output file is enriched with a hash value. It's a md5 sum which depends on the content of the file and some other information., _(*19)

Filter img

{{ 'img/header.jpg' | img }}

Renders the HTML, _(*20)

<img src="<asset_output_web_prefix>/img/header_813dec0e6ec1420d101c3f07bfc0a135.jpg">

and writes the file, _(*21)

<asset_output_path>/img/header_813dec0e6ec1420d101c3f07bfc0a135.jpg

Filter css

{{ 'css/style.css' | css }}

Renders the HTML, _(*22)

<link rel="stylesheet" href="<asset_output_web_prefix>/css/style_813dec0e6ec1420d101c3f07bfc0a135.css"/>

and writes the file, _(*23)

<asset_output_path>/css/style_813dec0e6ec1420d101c3f07bfc0a135.css

Filter js

{{ 'js/app.js' | js }}

Renders the HTML, _(*24)

<script src="<asset_output_web_prefix>/js/app_813dec0e6ec1420d101c3f07bfc0a135.js"></script>

and writes the file, _(*25)

<asset_output_path>/js/app_813dec0e6ec1420d101c3f07bfc0a135.js

Filter options for img|css|js

If you want to set some attributes to the tags use the attr options. This options only effects the render output., _(*26)

Example with img, _(*27)

{{ 'img/header.jpg' | img({attr:{class:'img-responsive', id:"header-image", alt:"Some importend text about the image"}}) }}

Renders the HTML, _(*28)

<img class="img-responsive" id="header-image" alt="Some importend text about the image" src="<asset_output_web_prefix>/img/header_813dec0e6ec1420d101c3f07bfc0a135.jpg">

Filter options for all tags if the file extension is jpg|jpeg|png|gif

Like the shining example jekyll-assets it uses ImageMagick for image manipulation., _(*29)

You can use it with every filter but it should only usefull with img and asset_path, _(*30)

This options of the convert-command are used:, _(*31)

• quality
• resize
• crop
• gravity only if crop options is present.

Also when crop is used a +repage will appended, look here repage for more information, _(*32)

Here an example with all options at once, _(*33)

{{ 'img/feature-image.jpg' | img({resize: '300x300^', crop: '300x300+0+0', gravity: 'SouthEast', quality:60 }) }}

This creates a new images which is quadratic., _(*34)

• resize: '300x300^' means resize the image that it cover a 300px times 300px area
• crop: '300x300+0+0' means crop to 300px times 300px but
• gravity: 'SouthEast' use the bottom-right corner
• quality:60 reduce the quality to 60%.

Renders the HTML, _(*35)

<img src="<asset_output_web_prefix>/img/feature-image_6fa6fa3af470d85af98ac7f7b8d5c933.jpg">

and writes the file, _(*36)

<asset_output_path>/img/feature-image_6fa6fa3af470d85af98ac7f7b8d5c933.jpg

Be informed different image transformation options lead to other hash values used for the file., _(*37)

So, _(*38)

{{ 'img/feature-image.jpg' | img }}

will not create the file, _(*39)

<asset_output_path>/img/feature-image_6fa6fa3af470d85af98ac7f7b8d5c933.jpg

Cache folder

For a better performance the plugin cached all files in the folder .cache/assets. This saved time for the image manipulation. It will not clear old unused file. So please clean it up from time to time., _(*40)

asset boost on apache webserver

As an extra you can asset boost your site if it runs with an apache webserver with the following .htaccess options., _(*41)

RewriteEngine On

RewriteCond %{HTTP:Accept-Encoding} gzip
RewriteCond %{REQUEST_FILENAME}.gz -f
RewriteRule ^(.+\.(xml|html|css|js|eot|eot|woff2|woff|ttf|svg))$ /$1.gz [L]

<FilesMatch "\.(xml|xml.gz|html|htm|html.gz|htm.gz)$">
Header set Cache-Control "no-cache, no-store, must-revalidate"
Header set Pragma "no-cache"
</FilesMatch>

<FilesMatch "\.(gz)$">
Header set Vary "Accept-Encoding" 
Header set Content-Encoding "gzip"
</FilesMatch>

<FilesMatch "\.js.gz$">
Header set Content-Type "application/javascript"
</FilesMatch>

<FilesMatch "\.css.gz$">
Header set Content-Type "text/css; charset=UTF-8"
</FilesMatch>

<FilesMatch "_[a-f0-9]{32}\.(ico|pdf|flv|jpg|jpeg|png|gif|swf|ico.gz|pdf.gz|flv.gz|jpg.gz|jpeg.gz|png.gz|gif.gz|swf.gz|js|css|css.gz|js.gz)$">
ExpiresActive On
ExpiresDefault "access plus 1 year"
Header set Cache-Control "max-age=8916000, public"
</FilesMatch>

I generate the gzip files as an after build step., _(*42)

Wished features for the next releases

• a posteriori run of jpegoptim und optipng
• filter for outputing raw asset to twig. E.g. inline js or css
• filter for outputing transformed image to twig. E.g. inline base64 images
• asset boost configs for other web servers, I hope for pull requests
• render css|js or other files with twig before coping, this allows to inject e.g. colors from config.yml to the style files.
• scss processing
• babel processing