A Hexo plugins which helps to introduce low quality image placeholders to the theme
npm i hexo-filter-lqip --save
Install this plugin for the theme and use the view helper to render a placeholder.
lqipFor(path_to_asset, options)
- String *path_to_asset - a path to the image
- Object options
- String [type] - a type of placeholder, see the list of available types, defaults to the
default_type
as configured
- String [type] - a type of placeholder, see the list of available types, defaults to the
Returns a CSS value for background-image
property, which is a simplified version of the original image.
Example for EJS
<div
style="background-image: <%- lqip_for('/content/my-photo.jpg') %>"
></div>
To make it work as a real placeholder, there must be a piece of JavaScript code, which will eventually replace the placeholder with the original image. It can be done by adding a data attribute with the original image path:
<div
style="background-image: <%- lqip_for('/content/my-photo.jpg') %>"
data-lazy-src="/content/my-photo.jpg"
></div>
and replacing the background-image
CSS property with the original image once it's loaded:
(function () {
var lazyImages = document.querySelectorAll('[data-lazy-src]')
lazyImages.forEach(function (img) {
var url = img.dataset.lazySrc
var image = new Image()
image.onload = function () {
img.style.backgroundImage = 'url(' + url + ')'
}
image.src = url
})
})()
For even more improvement, the script could load only images that are visible on the screen.
Type name: potrace
Uses the posterize
function from potrace to generate simplified SVG version of the image. The output
is optimized with SVGO and inlined.
Type name: color
Plain background, the dominant color extracted from the image.
Put your configuration in the theme _config.yml
under lqip
key.
You can also use the overriding theme config
feature of Hexo. Available options are the following:
Defaults to 'lqip-cache.json'. Could be a string with a file name of the cache.
You can also set to false
to disable caching.
Ideally, the cache file should not be checked in into repository.
The priority of the after_generate
filter. Defaults to 10.
You can find more information about priority in Filter documentation.
Defaults to potrace
. Use this type if not specified as a param to lqip_for
helper.
Configuration specific to potrace
type. All keys except canvas_size
are passed to the posterize
function of potrace
Before the image is passed to potrace, it's resized to this size.
lqip:
default_type: potrace
potrace:
canvas_size:
width: 140
steps: 2
color: '#dedede'
background: transparent
If something goes wrong, use --debug
option to get all information about the generating of the blog and extra
information about low-quality image placeholders processing.
hexo generate --debug
After changing parameters of placeholder it may be required to clean cache, by removing the cache file manually or with:
hexo clean
You can see it put together in the hexo-lqip-example repository.
- Using SVG as placeholders
- Willian Justen pictures used for the demo