109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
# [Grav](http://getgrav.org/) Image Srcset Plugin
|
|
|
|
Adds a `srcset`-attribute to `img`-elements to allow for responsive images in Markdown. This allows [modern browsers](http://caniuse.com/#feat=srcset) to load the image which best fits within the viewport, based on available images and sizes, essentially choosing the best image to reduce loading times (see [RespImg](https://responsiveimages.org/)).
|
|
|
|
Thus, on a small mobile screen this would load a much smaller image than on a large desktop. From this:
|
|
|
|
```html
|
|
<img title="Street view from the east" alt="Street view" src="street.jpg" />
|
|
```
|
|
|
|
To this:
|
|
|
|
```html
|
|
<img
|
|
title="Street view from the east"
|
|
alt="Street view"
|
|
src="street.jpg"
|
|
srcset="
|
|
street-320.jpg 320w,
|
|
street-480.jpg 480w,
|
|
street-640.jpg 640w,
|
|
street-960.jpg 960w,
|
|
street-1280.jpg 1280w,
|
|
street-1600.jpg 1600w,
|
|
street-1920.jpg 1920w,
|
|
street-2240.jpg 2240w
|
|
"
|
|
sizes="100vw"
|
|
/>
|
|
```
|
|
|
|
This is only applied to image-elements generated from Markdown. Depends on [PHP Html Parser v1.7.0](https://github.com/paquettg/php-html-parser/) for DOM parsing and manipulation of `srcset` and `sizes`.
|
|
|
|
# Installation and Configuration
|
|
|
|
1. Download the zip version of [this repository](https://github.com/OleVik/grav-plugin-imgsrcset) and unzip it under `/your/site/grav/user/plugins`.
|
|
2. Rename the folder to `imgsrcset`.
|
|
|
|
You should now have all the plugin files under
|
|
|
|
/your/site/grav/user/plugins/imgsrcset
|
|
|
|
The plugin is enabled by default, and can be disabled by copying `user/plugins/imgsrcset/imgsrcset.yaml` into `user/config/plugins/imgsrcset.yaml` and setting `enabled: false`. For a simple Twig-integration see [this gist](https://gist.github.com/OleVik/a7604215f127763b71bd8b8788d45cfd).
|
|
|
|
**Note**: The plugin needs Twig to be processed first, so be sure to set `twig_first` to `true` in `system.yaml`, like this:
|
|
|
|
```
|
|
pages:
|
|
twig_first: true
|
|
```
|
|
|
|
## Generating images
|
|
|
|
This plugin does **not** leverage Grav's media caching mechanisms, it simply circumvenes the need for caching by assuming that images are generated outside of Grav. This is necessary because Grav currently uses the Gregwar library, which relies on PHP's GD-module for image manipulation, and it handles large or many images poorly - indeed it tends to crash both caching and Grav itself. Thus by creating the images outside of this system the same quality and automation is achieved.
|
|
|
|
**For an example of generating responsive images with NodeJS and Gulp see [this gist](https://gist.github.com/OleVik/f2c8b51a7153743b13607072c27cf8d2).**
|
|
|
|
## Widths
|
|
|
|
The `widths` setting is a YAML sequence wherein each integer represents the width of the image, defaulting to:
|
|
|
|
```yaml
|
|
- 320
|
|
- 480
|
|
- 640
|
|
- 960
|
|
- 1280
|
|
- 1600
|
|
- 1920
|
|
- 2240
|
|
```
|
|
|
|
## Sizes
|
|
|
|
The `sizes` setting is a YAML string defining the [sizes](https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-sizes)-attribute, defaulting to:
|
|
|
|
```yaml
|
|
sizes: "100vw"
|
|
```
|
|
|
|
## Images
|
|
|
|
The plugin expects the images to be in the same folder as the source image. So, for the case of `street.jpg`, the page folder should contain:
|
|
|
|
```bash
|
|
street.jpg
|
|
street-320.jpg
|
|
street-480.jpg
|
|
street-640.jpg
|
|
street-960.jpg
|
|
street-1280.jpg
|
|
street-1600.jpg
|
|
street-1920.jpg
|
|
street-2240.jpg
|
|
```
|
|
|
|
## Per Page Options
|
|
|
|
Configuration-options may also be set on an individual Page, using the following FrontMatter:
|
|
|
|
```yaml
|
|
imgsrcset:
|
|
enabled: true
|
|
widths: widths
|
|
sizes: sizes
|
|
```
|
|
|
|
MIT License 2019 by [Ole Vik](http://github.com/olevik).
|