Images
THIS IS NOT YET IMPLEMENTED
Rocket does handle content images automatically by
- producing multiple sizes so users download images that are meant for their resolution
- outputting multiple formats so the device can choose the best image format it supports
And the best thing is you don't need to do anything.
Usage
If you are using markdown images you are good to go.
![My Image](path/to/image.jpg)
will result in
<picture>
<source
type="image/avif"
srcset="/images/5f03d82-300.avif 300w, /images/5f03d82-820.avif 820w"
sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
/>
<source
type="image/jpeg"
srcset="/images/5f03d82-300.jpeg 300w, /images/5f03d82-820.jpeg 820w"
sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
/>
<img
alt="My Image"
rocket-image="responsive"
src="/images/5f03d82-300.jpeg"
width="300"
height="158"
loading="lazy"
decoding="async"
/>
</picture>
Benefits
The main benefit is that we can serve the correct size and optimal image format depending on the browser capabilities leading to optimal loading times on different systems.
-
Smaller images for smaller screens
When providing
srcset
andsizes
the browser can decide which image makes the most sense to download. This will lead to much faster websites especially on mobile where smaller images can be served. If you wanna know more check out The anatomy of responsive images. -
Serve the best/smallest image format the browser understands
There are currently ~3 formats you may want to consider
avif
,webp
andjpg
. The improvements are huge webp is ~30% and avif ~50% smaller then the original jpg.
Adding a caption
If you want to describe your image in more detail you can add a caption
![My Image](path/to/image.jpg 'My caption text')
will result in
<figure>
<picture>
<!-- picture code the same as above -->
</picture>
<figcaption>My caption text</figcaption>
</figure>
Adjusting options
Under the hood it is using 11ty/image and all its options are available.
If you are using a layout preset like @rocket/launch
then you probably don't want to touch/change these options as the preset will set it for you according to its layout needs.
The default preset for regular markdown content is available as responsive
.
👉 config/rocket.config.js
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
imagePresets: {
responsive: {
widths: [300, 820],
formats: ['avif', 'jpeg'],
sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
},
},
};
Ignoring Images
Files ending in .svg
or that include rocket-ignore.
will remain untouched.
For example
![Logo stays svg](logo.svg)
![Ignore by file name](my-image.rocket-unresponsive.jpg)
![My Image Alternative Text](my-image.jpeg)
becomes
<img src="logo.svg" alt="Logo stays svg" rocket-image="responsive" />
<img src="my-image.rocket-unresponsive.jpg" alt="Ignore by file name" rocket-image="responsive" />
<picture>[...] </picture>
Adjusting ignore function
The default ignore function looks like this
/**
* The default responsive ignore function will ignore files
* - ending in `.svg`
* - containing `rocket-unresponsive.`
*
* @param {object} opts
* @param {string} opts.src
* @param {string} opts.title
* @param {string} opts.alt
* @param {{name: string, value: string}[]} opts.attributes
* @returns {boolean}
*/
function ignore({ src }) {
return src.endsWith('svg') || src.includes('rocket-unresponsive.');
}
and you can adjust it by setting it via the imagePreset
.
For this example we want to also ignore .jpeg
files.
👉 config/rocket.config.js
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
imagePresets: {
responsive: {
// ...
ignore: ({ src }) =>
src.endsWith('.jpeg') || src.endsWith('svg') || src.includes('rocket-unresponsive.'),
},
},
};
With that setting we get the following behavior
![Logo stays svg](logo.svg)
![Ignore by file name](my-image.rocket-unresponsive.jpg)
![My Image Alternative Text](my-image.jpeg)
becomes
<img src="logo.svg" alt="Logo stays svg" rocket-image="responsive" />
<img src="my-image.rocket-unresponsive.jpg" alt="Ignore by file name" rocket-image="responsive" />
<img src="my-image.jpeg" alt="My Image Alternative Text" rocket-image="responsive" />
Defining your own presets
You can add your own image preset like so
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
imagePresets: {
'my-image-preset': {
widths: [30, 60],
formats: ['avif', 'jpeg'],
sizes: '(min-width: 1024px) 30px, 60px',
},
},
};
Once that imagePreset
is defined you can use it by adding it to any img
tag.
<img src="./path/to/image.jpg" alt="my alt" rocket-image="my-image-preset" />
How does it work?
- Each markdown image
![my image](path/to/image.jpg)
gets rendered as<img src="path/to/image.jpg" alt="my image" rocket-image="responsive">
- We parse the html output and process every image which has
rocket-image
- Get the image preset settings from the name e.g.
rocket-image="my-image-preset"
readsimagePreset['my-image-preset']
- Pass the settings onto
@11ty/image
to generate the image sizes and formats - With the metadata we render the html
Default Formats
An image file format is a way of storing common image formats. Each format varies in capabilities like compression algorithm, availability, progressive rendering, encode and decode time, ... Ultimately newer formats are usually smaller while retaining image quality which leads to faster websites.
By default, we generate avif
and jpg
because
- we only want to generate two versions to limit CI time and html size
avif
is significantly smaller thanwebp
avif
is available in- Chrome since August 2020
- Firefox since June 2021
jpg
as a fallback for Edge, Safari, IE11webp
would only help a small percentage of Edge & Safari on macOS 11 (Big Sur) users
This leads to the following situation:
- Chrome, Firefox gets the small
avif
- Edge, Safari, IE11 gets the bigger
jpg
To learn more about avif
take a look at AVIF has landed.
If you want to add webp
(or replace avif
with it) you can do so by setting the formats
👉 config/rocket.config.js
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
imagePresets: {
responsive: {
formats: ['avif', 'webp', 'jpeg'],
},
},
};
Default widths
In order to understand the need for having a single image in multiple resolutions we need to understand that our website is served to many different environments and each may come with its own specific device pixel ratio (DPR). The device pixel ratio is the ratio between physical pixels and logical pixels. For instance, the Galaxy S20 report a device pixel ratio of 3, because the physical linear resolution is triple the logical linear resolution.
Physical resolution: 1440 x 3200 Logical resolution: 480 x 1067
And 1440 / 480 = 3.
By default, we generate the following widths 600
, 900
and 1640
because
- we only want to generate a small amount of widths to limit CI time and service worker cache size
600
is good for mobile with DRP 2900
is good for mobile with DRP 3 and desktop with DPR of 11640
is good for desktop with DPR of 2
If you want to add more widths you can add them to widths
.
👉 config/rocket.config.js
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
imagePresets: {
responsive: {
widths: [300, 600, 900, 1200, 1640],
sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
},
},
};
As an end user in most cases you don't want to mess with this as a layout preset should set this for you. If you are building your own layout preset then be sure to set widths
and sizes
via adjustImagePresets
export function myPreset() {
return {
adjustImagePresets: imagePresets => ({
...imagePresets,
responsive: {
...imagePresets.responsive,
widths: [600, 900, 1640],
sizes: '(min-width: 1024px) 820px, calc(100vw - 40px)',
},
}),
};
}