15 |
16 |
17 |
--------------------------------------------------------------------------------
/docs/tutorial/03-resized-images/.eleventy.js:
--------------------------------------------------------------------------------
1 | export default async function (eleventyConfig) {
2 | import markdownIt from 'markdown-it';
3 | import markdownItAttributes from 'markdown-it-attrs';
4 | eleventyConfig.setLibrary('md', markdownIt().use(markdownItAttributes));
5 |
6 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
7 | eleventyConfig.addPlugin(imagesResponsiver);
8 |
9 | eleventyConfig.addPassthroughCopy('src/assets');
10 |
11 | return {
12 | dir: {
13 | input: 'src',
14 | output: 'dist',
15 | },
16 | };
17 | };
18 |
--------------------------------------------------------------------------------
/docs/tutorial/02-with-plugin-default/.eleventy.js:
--------------------------------------------------------------------------------
1 | export default async function (eleventyConfig) {
2 | import markdownIt from 'markdown-it';
3 | import markdownItAttributes from 'markdown-it-attrs';
4 | eleventyConfig.setLibrary('md', markdownIt().use(markdownItAttributes));
5 |
6 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
7 | eleventyConfig.addPlugin(imagesResponsiver);
8 |
9 | eleventyConfig.addPassthroughCopy('src/assets');
10 |
11 | return {
12 | dir: {
13 | input: 'src',
14 | output: 'dist',
15 | },
16 | };
17 | };
18 |
--------------------------------------------------------------------------------
/docs/tutorial/04-images-dimensions/.eleventy.js:
--------------------------------------------------------------------------------
1 | export default async function (eleventyConfig) {
2 | import markdownIt from 'markdown-it';
3 | import markdownItAttributes from 'markdown-it-attrs';
4 | eleventyConfig.setLibrary('md', markdownIt().use(markdownItAttributes));
5 |
6 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
7 | eleventyConfig.addPlugin(imagesResponsiver);
8 |
9 | eleventyConfig.addPassthroughCopy('src/assets');
10 |
11 | return {
12 | dir: {
13 | input: 'src',
14 | output: 'dist',
15 | },
16 | };
17 | };
18 |
--------------------------------------------------------------------------------
/docs/tutorial/01-without-plugin/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {.logo}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | 
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/docs/tutorial/03-resized-images/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {.logo}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | 
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/docs/tutorial/02-with-plugin-default/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {.logo}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | 
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/docs/tutorial/00-preparation/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** |
2 |
3 | # Step 0: Get the resources to follow this tutorial
4 |
5 | Get the sources from the repository.
6 |
7 | Clone it with Git into your local folder (change `my-local-folder` to what you want):
8 |
9 | ```bash
10 | git clone git@github.com:nhoizey/images-responsiver.git my-local-folder
11 | ```
12 |
13 | Then go into the first example folder with your terminal:
14 |
15 | ```bash
16 | cd my-local-folder/docs/eleventy-plugin-images-responsiver/tutorial/01-without-plugin
17 | ```
18 |
19 | And let's go for **[step 1](../01-without-plugin/#readme)**!
20 |
--------------------------------------------------------------------------------
/docs/tutorial/06-presets-properties/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {data-responsiver=logo}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | {width=1600}{height=1000}
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/docs/tutorial/04-images-dimensions/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {.logo}{width=400}{height=400}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | {width=1600}{height=1000}
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/docs/tutorial/05-presets/src/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: base.njk
3 | title: images-responsiver
4 | ---
5 |
6 | {.logo}{width=400}{height=400}{data-responsiver=logo}
7 |
8 | `images-responsiver` is **a simple solution for most responsive images needs**. It transforms simple `` HTML tags into better responsive images syntax with `srcset` and `sizes` attributes.
9 |
10 | Here is a simple image:
11 |
12 | {width=1600}{height=1000}
13 |
14 | Download the photo for free [on Unsplash](https://unsplash.com/photos/0jj1xNsSOBo).
15 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Feature request
3 | about: Suggest an idea for this project
4 | title: '[Feature request] '
5 | labels: ''
6 | assignees: ''
7 | ---
8 |
9 | **Is your feature request related to a problem? Please describe.**
10 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
11 |
12 | **Describe the solution you'd like**
13 | A clear and concise description of what you want to happen.
14 |
15 | **Describe alternatives you've considered**
16 | A clear and concise description of any alternative solutions or features you've considered.
17 |
18 | **Additional context**
19 | Add any other context or screenshots about the feature request here.
20 |
--------------------------------------------------------------------------------
/docs/tutorial/05-presets/.eleventy.js:
--------------------------------------------------------------------------------
1 | export default async function (eleventyConfig) {
2 | import markdownIt from 'markdown-it';
3 | import markdownItAttributes from 'markdown-it-attrs';
4 | eleventyConfig.setLibrary('md', markdownIt().use(markdownItAttributes));
5 |
6 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
7 | const presets = {
8 | default: {
9 | sizes: '(max-width: 45em) 90vw, 40em',
10 | },
11 | logo: {
12 | sizes: '(max-width: 45em) 18vw, 8em',
13 | },
14 | };
15 | eleventyConfig.addPlugin(imagesResponsiver, presets);
16 |
17 | eleventyConfig.addPassthroughCopy('src/assets');
18 |
19 | return {
20 | dir: {
21 | input: 'src',
22 | output: 'dist',
23 | },
24 | };
25 | };
26 |
--------------------------------------------------------------------------------
/eleventy-plugin-images-responsiver.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | import pkg from './package.json' with { type: 'json' };
4 |
5 | import imagesResponsiver from 'images-responsiver';
6 |
7 | export default async (eleventyConfig, userOptions = {}) => {
8 | // First check if the plugin is used with a compatible version of Eleventy
9 | try {
10 | eleventyConfig.versionCheck(pkg['11ty'].compatibility);
11 | } catch (e) {
12 | console.error(
13 | `[eleventy-plugin-image-responsiver] Plugin compatibility error ${e.message}`
14 | );
15 | return;
16 | }
17 |
18 | eleventyConfig.addTransform('imagesResponsiver', function (content) {
19 | if (this.page.outputPath && this.page.outputPath.endsWith('.html')) {
20 | return imagesResponsiver(content, userOptions, this.page.url);
21 | }
22 | return content;
23 | });
24 | };
25 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve
4 | title: '[Bug] '
5 | labels: 'type: bug 🐛'
6 | assignees: ''
7 | ---
8 |
9 | **Describe the bug**
10 | A clear and concise description of what the bug is.
11 |
12 | **To Reproduce**
13 | Steps to reproduce the behavior:
14 |
15 | 1. Install '…'
16 | 2. Configure '…'
17 | 3. Run '…'
18 | 4. See error
19 |
20 | **Expected behavior**
21 | A clear and concise description of what you expected to happen.
22 |
23 | **Screenshots / logs**
24 | If applicable, add screenshots and/or console logs to help explain your problem.
25 |
26 | **Environment**
27 |
28 | - OS and version: [e.g. macOS 10.14.5]
29 | - Eleventy version: [e.g. 2.0.0]
30 | - `eleventy-plugin-images-responsiver` version: [e.g. 2.0.1]
31 |
32 | **Additional context**
33 | Add any other context about the problem here.
34 |
--------------------------------------------------------------------------------
/docs/tutorial/06-presets-properties/.eleventy.js:
--------------------------------------------------------------------------------
1 | export default async function (eleventyConfig) {
2 | import markdownIt from 'markdown-it';
3 | import markdownItAttributes from 'markdown-it-attrs';
4 | eleventyConfig.setLibrary('md', markdownIt().use(markdownItAttributes));
5 |
6 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
7 | const presets = {
8 | default: {
9 | sizes: '(max-width: 45em) 90vw, 40em',
10 | attributes: {
11 | loading: 'lazy',
12 | },
13 | },
14 | logo: {
15 | sizes: '(max-width: 45em) 18vw, 8em',
16 | classes: ['logo'],
17 | attributes: {
18 | width: '400',
19 | height: '400',
20 | },
21 | },
22 | };
23 | eleventyConfig.addPlugin(imagesResponsiver, presets);
24 |
25 | eleventyConfig.addPassthroughCopy('src/assets');
26 |
27 | return {
28 | dir: {
29 | input: 'src',
30 | output: 'dist',
31 | },
32 | };
33 | };
34 |
--------------------------------------------------------------------------------
/.github/workflows/tests.yml:
--------------------------------------------------------------------------------
1 | name: Tests CI
2 | on: [push, pull_request]
3 | jobs:
4 | tests:
5 | runs-on: ubuntu-latest
6 |
7 | steps:
8 | - uses: actions/checkout@v4
9 |
10 | - name: Get npm cache directory
11 | id: npm-cache
12 | run: |
13 | echo "::set-output name=dir::$(npm config get cache)"
14 |
15 | - name: Use cache
16 | uses: actions/cache@v4
17 | with:
18 | path: ${{ steps.npm-cache.outputs.dir }}
19 | key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
20 | restore-keys: ${{ runner.os }}-node-
21 |
22 | - name: Select Node.js version
23 | uses: actions/setup-node@v4
24 | with:
25 | node-version-file: '.nvmrc'
26 | cache: 'npm'
27 |
28 | - name: Install dependencies
29 | run: npm ci
30 |
31 | - name: Run tests
32 | run: npm test
33 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2020 Nicolas Hoizey
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/docs/tutorial/01-without-plugin/dist/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | images-responsiver
7 |
8 |
9 |
10 |
11 |
12 |
images-responsiver
13 |
14 |
15 | images-responsiver is
16 | a simple solution for most responsive images needs. It
17 | transforms simple <img src="…" /> HTML tags
18 | into better responsive images syntax with srcset and
19 | sizes attributes.
20 |
21 |
Here is a simple image:
22 |
23 |
27 |
28 |
29 | Download the photo for free
30 | on Unsplash.
31 |
43 |
44 |
45 |
--------------------------------------------------------------------------------
/docs/debugging.md:
--------------------------------------------------------------------------------
1 | # Debugging
2 |
3 | You can run Eleventy build in debug mode to get informations and warnings about your Markdown, HTML or plugin options.
4 |
5 | Add `DEBUG=*` in front of the command to get messages in the console, including a lot of debug message from Eleventy, not specific to this plugin.
6 |
7 | Use `DEBUG=image-responsiver:*` to only get debug messages from the plugin:
8 |
9 | ```bash
10 | images-responsiver:info Transforming my-logo.png +0ms
11 | images-responsiver:warning The image should have a width attribute: my-logo.png +0ms
12 | images-responsiver:info Transforming colorful-netherlands.jpg +2ms
13 | images-responsiver:warning The image should have a width attribute: colorful-netherlands.jpg +1ms
14 | ```
15 |
16 | `images-responsiver` (on which this plugin is based) uses the great [debug](https://github.com/visionmedia/debug) module to provide these debug messages.
17 |
18 | You can use different values for `DEBUG=`:
19 |
20 | | `DEBUG=*` | get all messages, even from Eleventy and other packages |
21 | | `DEBUG=images-responsiver:*` | get all messages, only from `images-responsiver` |
22 | | `DEBUG=images-responsiver:info` | get only information messages from `images-responsiver` |
23 | | `DEBUG=images-responsiver:warning` | get only warning messages from `images-responsiver` |
24 | | `DEBUG=images-responsiver:error` | get only error messages from `images-responsiver` |
25 | | `DEBUG=images-responsiver:error,images-responsiver:warning` or `DEBUG=images-responsiver:*,-images-responsiver:info` | get only warning and error messages from `images-responsiver` |
26 |
--------------------------------------------------------------------------------
/docs/tutorial/06-presets-properties/dist/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | images-responsiver
7 |
8 |
9 |
10 |
11 |
12 |
images-responsiver
13 |
14 |
images-responsiver is a simple solution for most responsive images needs. It transforms simple <img src="…" /> HTML tags into better responsive images syntax with srcset and sizes attributes.
20 |
21 |
22 |
--------------------------------------------------------------------------------
/docs/tutorial/02-with-plugin-default/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 1](../01-without-plugin/#readme)** |
2 |
3 | # Step 2: Default behaviour with the plugin
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, no image should be visible… 😅
19 |
20 | Here is a screenshot on desktop:
21 |
22 | 
23 |
24 | And here on simulated mobile:
25 |
26 | 
27 |
28 | Fortunately, there are `alt` attributes! 💪
29 |
30 | ## How does it work? (even if you might think it is not)
31 |
32 | We installed the plugin:
33 |
34 | ```bash
35 | npm install eleventy-plugin-images-responsiver --save-dev
36 | ```
37 |
38 | And here's what we added to `.eleventy.js`:
39 |
40 | ```javascript
41 | import imagesResponsiver from 'eleventy-plugin-images-responsiver';
42 | eleventyConfig.addPlugin(imagesResponsiver);
43 | ```
44 |
45 | This is the simplest way to add the plugin without any specific configuration.
46 |
47 | Images are not visible because the transformed HTML (using default configuration) tells the browsers about images with names like `colorful-netherlands-320.jpg`, `colorful-netherlands-560.jpg` while we actualy only have one `colorful-netherlands.jpg` image file.
48 |
49 | # Now… what?
50 |
51 | Let's see how to provide these resized images to browsers in **[step 3](../03-resized-images/#readme)**.
52 |
--------------------------------------------------------------------------------
/docs/tutorial/03-resized-images/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 2](../02-with-plugin-default/#readme)** |
2 |
3 | # Step 3: Resized images
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, images should be back. 🥳
19 |
20 | Here is a screenshot on desktop:
21 |
22 | 
23 |
24 | And here on simulated mobile:
25 |
26 | 
27 |
28 | Oh… well, the photo is there in both screenshots, but the logo is there only on mobile… 🤔
29 |
30 | ## How does it (partially) work?
31 |
32 | We didn't change anything in `.eleventy.js`.
33 |
34 | We created the multiple resized images manually, so that they are available for the browser.
35 |
36 | Unfortunately, the pristine (a.k.a. "untouched original") logo image is only 400 pixels wide, so we couldn't create images `my-logo-560.png`, `my-logo-800.png`, `my-logo-1040.png` and `my-logo-1280.png` the HTML is telling the browser about!
37 |
38 | So while the `my-logo-320.png` version is enough for the mobile view, the desktop view tries to load a larger one (after all, our HTML tells him it is available) and fails.
39 |
40 | # Now… what?
41 |
42 | So we have to find a way to tell the plugin the image's width, so that it doesn't add a larger one to the transformed HTML.
43 |
44 | Let's see how to do this in **[step 4](../04-images-dimensions/#readme)**.
45 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "eleventy-plugin-images-responsiver",
3 | "version": "3.0.0",
4 | "description": "Global solution for responsive images in Eleventy, allowing authors to use Markdown syntax for image and yet get responsive images in generated HTML.",
5 | "main": "eleventy-plugin-images-responsiver.js",
6 | "repository": {
7 | "type": "git",
8 | "url": "git+https://github.com/nhoizey/eleventy-plugin-images-responsiver.git"
9 | },
10 | "files": [],
11 | "type": "module",
12 | "scripts": {
13 | "lint": "eslint . --ext js --quiet --fix",
14 | "test": "echo \"No test specified yet\"",
15 | "prepare": "node .husky/install.mjs",
16 | "release": "np"
17 | },
18 | "keywords": [
19 | "static-site-generator",
20 | "static-site",
21 | "website",
22 | "blog",
23 | "generator",
24 | "eleventy",
25 | "eleventy-plugin",
26 | "11ty",
27 | "html",
28 | "markdown",
29 | "image",
30 | "images",
31 | "responsive",
32 | "RWD",
33 | "srcset",
34 | "sizes",
35 | "Cloudinary"
36 | ],
37 | "author": "Nicolas Hoizey",
38 | "license": "MIT",
39 | "dependencies": {
40 | "images-responsiver": "^1.13.0"
41 | },
42 | "devDependencies": {
43 | "@commitlint/cli": "^19.5.0",
44 | "@commitlint/config-conventional": "^19.5.0",
45 | "eslint": "^9.13.0",
46 | "eslint-config-prettier": "^9.1.0",
47 | "eslint-plugin-prettier": "^5.2.1",
48 | "husky": "^9.1.6",
49 | "np": "^10.0.7"
50 | },
51 | "bugs": {
52 | "url": "https://github.com/nhoizey/eleventy-plugin-images-responsiver/issues"
53 | },
54 | "homepage": "https://nhoizey.github.io/eleventy-plugin-images-responsiver/",
55 | "gitHead": "e59f7fb0422676b8928998b5233c4824ed695c10",
56 | "11ty": {
57 | "compatibility": ">=3 <4"
58 | }
59 | }
60 |
--------------------------------------------------------------------------------
/docs/tutorial/04-images-dimensions/dist/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | images-responsiver
7 |
8 |
9 |
10 |
11 |
images-responsiver
12 |
13 |
22 |
23 |
24 | images-responsiver is
25 | a simple solution for most responsive images needs. It
26 | transforms simple <img src="…" /> HTML tags
27 | into better responsive images syntax with srcset and
28 | sizes attributes.
29 |
30 |
Here is a simple image:
31 |
32 |
46 |
47 |
48 | Download the photo for free
49 | on Unsplash.
50 |
25 | images-responsiver is
26 | a simple solution for most responsive images needs. It
27 | transforms simple <img src="…" /> HTML tags
28 | into better responsive images syntax with srcset and
29 | sizes attributes.
30 |
31 |
Here is a simple image:
32 |
33 |
48 |
49 |
50 | Download the photo for free
51 | on Unsplash.
52 |
29 | images-responsiver is
30 | a simple solution for most responsive images needs. It
31 | transforms simple <img src="…" /> HTML tags
32 | into better responsive images syntax with srcset and
33 | sizes attributes.
34 |
35 |
Here is a simple image:
36 |
37 |
50 |
51 |
52 | Download the photo for free
53 | on Unsplash.
54 |
29 | images-responsiver is
30 | a simple solution for most responsive images needs. It
31 | transforms simple <img src="…" /> HTML tags
32 | into better responsive images syntax with srcset and
33 | sizes attributes.
34 |
35 |
Here is a simple image:
36 |
37 |
50 |
51 |
52 | Download the photo for free
53 | on Unsplash.
54 |
55 |
56 |
57 |
58 |
--------------------------------------------------------------------------------
/docs/tutorial/01-without-plugin/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 0](../00-preparation/#readme)** |
2 |
3 | # Step 1: Default behaviour without the plugin
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, both images should be visible.
19 |
20 | Here is a screenshot on desktop:
21 |
22 | 
23 |
24 | And here on simulated mobile:
25 |
26 | 
27 |
28 | We used this CSS file:
29 |
30 |
31 |
32 | We want the content to take 90 % of the available space, but never more than `40em` (better for readability of multi-lines texts), and the logo to use 20 % of this content width, floated on the right.
33 |
34 | _Note: We used the [Markdown-it Attributes plugin](https://github.com/arve0/markdown-it-attrs) to add a `logo` class to the logo image for styling (width, float on the right, etc.). This plugin allows adding attributes to elements using this syntax for example: `{.logo}`. This plugin will be even more useful later._
35 |
36 | We can open this page in different browsers, on different devices, with different viewport widths and screen densities, **the very same (potentially heavy) image files will be downloaded**. Not cool for people on small devices with low resolution, and potentially bad connexions.
37 |
38 | # Now… what?
39 |
40 | Let's try to enhance it with the plugin in **[step 2](../02-with-plugin-default/#readme)**.
41 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contribute
2 |
3 | ## Introduction
4 |
5 | First, thank you for considering contributing to `images-responsiver`! It's people like you that make the open source community such a great community! 😊
6 |
7 | We welcome any type of contribution, not only code. You can help with
8 |
9 | - **QA**: file bug reports, the more details you can give the better (e.g. screenshots, console logs, etc.)
10 | - **Marketing**: writing blog posts, howto's, printing stickers, …
11 | - **Community**: presenting the project at meetups, organizing a dedicated meetup for the local community, …
12 | - **Code**: take a look at the [open issues](https://github.com/nhoizey/images-responsiver/issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters. It helps us triage them.
13 |
14 | ## Your First Contribution
15 |
16 | Working on your first Pull Request? You can learn how from this _free_ series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
17 |
18 | ## Submitting code
19 |
20 | Any code change should be submitted as a pull request. The description should explain what the code does and give steps to execute it. The pull request should also contain tests.
21 |
22 | ## Code review process
23 |
24 | The bigger the pull request, the longer it will take to review and merge. Try to [break down large pull requests in smaller chunks](https://oncletom.io/2013/the-55-commits-syndrome/) that are easier to review and merge.
25 |
26 | It is also always helpful to have some context for your pull request. What was the purpose? Why does it matter to you?
27 |
28 | ## Questions
29 |
30 | If you have any questions, [create an issue](https://github.com/nhoizey/images-responsiver/issues/new/choose) (protip: do a quick search first to see if someone else didn't ask the same question before!).
31 |
32 | ## Credits
33 |
34 | ### Contributors
35 |
36 | Thank you to [all the people who have already contributed](https://github.com/nhoizey/images-responsiver/graphs/contributors) to `images-responsiver`!
37 |
38 |
39 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | In the interest of fostering an open and welcoming environment, we as
6 | contributors and maintainers pledge to making participation in our project and
7 | our community a harassment-free experience for everyone, regardless of age, body
8 | size, disability, ethnicity, sex characteristics, gender identity and expression,
9 | level of experience, education, socio-economic status, nationality, personal
10 | appearance, race, religion, or sexual identity and orientation.
11 |
12 | ## Our Standards
13 |
14 | Examples of behavior that contributes to creating a positive environment
15 | include:
16 |
17 | - Using welcoming and inclusive language
18 | - Being respectful of differing viewpoints and experiences
19 | - Gracefully accepting constructive criticism
20 | - Focusing on what is best for the community
21 | - Showing empathy towards other community members
22 |
23 | Examples of unacceptable behavior by participants include:
24 |
25 | - The use of sexualized language or imagery and unwelcome sexual attention or
26 | advances
27 | - Trolling, insulting/derogatory comments, and personal or political attacks
28 | - Public or private harassment
29 | - Publishing others' private information, such as a physical or electronic
30 | address, without explicit permission
31 | - Other conduct which could reasonably be considered inappropriate in a
32 | professional setting
33 |
34 | ## Our Responsibilities
35 |
36 | Project maintainers are responsible for clarifying the standards of acceptable
37 | behavior and are expected to take appropriate and fair corrective action in
38 | response to any instances of unacceptable behavior.
39 |
40 | Project maintainers have the right and responsibility to remove, edit, or
41 | reject comments, commits, code, wiki edits, issues, and other contributions
42 | that are not aligned to this Code of Conduct, or to ban temporarily or
43 | permanently any contributor for other behaviors that they deem inappropriate,
44 | threatening, offensive, or harmful.
45 |
46 | ## Scope
47 |
48 | This Code of Conduct applies both within project spaces and in public spaces
49 | when an individual is representing the project or its community. Examples of
50 | representing a project or community include using an official project e-mail
51 | address, posting via an official social media account, or acting as an appointed
52 | representative at an online or offline event. Representation of a project may be
53 | further defined and clarified by project maintainers.
54 |
55 | ## Enforcement
56 |
57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
58 | reported by contacting the project team at nicolas@hoizey.com. All
59 | complaints will be reviewed and investigated and will result in a response that
60 | is deemed necessary and appropriate to the circumstances. The project team is
61 | obligated to maintain confidentiality with regard to the reporter of an incident.
62 | Further details of specific enforcement policies may be posted separately.
63 |
64 | Project maintainers who do not follow or enforce the Code of Conduct in good
65 | faith may face temporary or permanent repercussions as determined by other
66 | members of the project's leadership.
67 |
68 | ## Attribution
69 |
70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72 |
73 | [homepage]: https://www.contributor-covenant.org
74 |
75 | For answers to common questions about this code of conduct, see
76 | https://www.contributor-covenant.org/faq
77 |
--------------------------------------------------------------------------------
/docs/tutorial/05-presets/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 4](../04-images-dimensions/#readme)** |
2 |
3 | # Step 5: Presets
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, all images are still there, and should weight much less! 💪
19 |
20 | Nothing changed visualy.
21 |
22 |
23 |
24 | ## How does it work?
25 |
26 | To make sure the browser knows the width of the image to render, we have to use the `sizes` attribute on each image. We need different `sizes` attribute values for different image use cases.
27 |
28 | But we don't want to repeat them for each images, and we want to provide content authors (even if that's us) with something as simple as possible so that they can focus on content.
29 |
30 | Let's define **presets**, and configuration options attached to them.
31 |
32 | First, we define a `default` preset that will be used for all images:
33 |
34 | ```javascript
35 | const presets = {
36 | default: {
37 | sizes: '(max-width: 45em) 90vw, 40em',
38 | },
39 | };
40 | ```
41 |
42 | We set the default `sizes` attribute value, considering we will never have any image larger than the content (remember, 90 % of the viewport but never more than `40em`).
43 |
44 | `(max-width: 45em) 90vw, 40em` now overrides the plugin's default value of `100vw`.
45 |
46 | We now need to add a specific overriding preset for the logo, which needs a different `sizes` value, because it takes only 20 % of the content area (20 % of `90vw` = `18vw`):
47 |
48 | ```javascript
49 | const presets = {
50 | default: {
51 | sizes: '(max-width: 45em) 90vw, 40em',
52 | },
53 | logo: {
54 | sizes: '(max-width: 45em) 18vw, 8em',
55 | },
56 | };
57 | ```
58 |
59 | We then use these `presets` as options for the plugin:
60 |
61 | ```javascript
62 | eleventyConfig.addPlugin(imagesResponsiver, presets);
63 | ```
64 |
65 | We also need a way for content authors to specify what preset an image should use, if the default one is not enough. We will use a `data-responsiver` data attribute, with the name of the preset as the value.
66 |
67 | Once again, the Markdown-it Attributes plugin helps us. We can change the Markdown for the logo from:
68 |
69 | ```markdown
70 | {.logo}{width=400}{height=400}
71 | ```
72 |
73 | To:
74 |
75 | ```markdown
76 | {.logo}{width=400}{height=400}{data-responsiver=logo}
77 | ```
78 |
79 | This syntax is becoming really verbose 😱, but **don't abandon now**, it's really worth it, and we'll see a little later how to make it easier for the content authors!
80 |
81 | Check the result of the transformation to see how the images now have different `sizes` attribute values:
82 |
83 | 
84 |
85 | You can also check the HTML:
86 |
87 |
88 |
89 | _Note: Each image can use multiple presets in the `data-responsiver` attribute, each value separated by a space (like classes). Attributes from each preset surcharges the previous one(s), in the order they're declared._
90 |
91 | # Now… what?
92 |
93 | Let's see how we can improve daily work of content authors in **[step 6](../06-presets-properties/#readme)**.
94 |
--------------------------------------------------------------------------------
/docs/tutorial/06-presets-properties/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 5](../05-presets/#readme)** |
2 |
3 | # Step 6: Presets properties
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, nothing changed visualy and the page weight is the same.
19 |
20 | However, if you check the source Markdown, it is simpler:
21 |
22 |
23 |
24 | See how the logo "lost" its class and dimensions? There is no `{.logo}{width=400}{height=400}` anymore.
25 |
26 | ## How does it work?
27 |
28 | We had these presets:
29 |
30 | ```javascript
31 | const presets = {
32 | default: {
33 | sizes: '(max-width: 45em) 90vw, 40em',
34 | },
35 | logo: {
36 | sizes: '(max-width: 45em) 18vw, 8em',
37 | },
38 | };
39 | ```
40 |
41 | ### Adding classes
42 |
43 | We can use presets to add classes to images.
44 |
45 | For example, we can add a `logo` class to every image using the `logo` preset with this syntax:
46 |
47 | ```javascript
48 | const presets = {
49 | default: {
50 | sizes: '(max-width: 45em) 90vw, 40em',
51 | },
52 | logo: {
53 | sizes: '(max-width: 45em) 18vw, 8em',
54 | classes: ['logo'],
55 | },
56 | };
57 | ```
58 |
59 | We could also add multiple classes, as in [Tailwind's floated image](https://tailwindcss.com/docs/float/#float-right):
60 |
61 | ```javascript
62 | const presets = {
63 | default: {
64 | sizes: '(max-width: 45em) 90vw, 40em',
65 | },
66 | logo: {
67 | sizes: '(max-width: 45em) 18vw, 8em',
68 | classes: ['float-right', 'ml-4', 'my-2', 'h-32'],
69 | },
70 | };
71 | ```
72 |
73 | Please, don't do this for production code, [extract components](https://tailwindcss.com/docs/extracting-components)… 🙏
74 |
75 | ### Adding other attributes
76 |
77 | We can also add other attributes to the images with the additional `attributes` property in each preset.
78 |
79 | For example, we can benefit from recent [native lazy-loading in modern browsers](https://web.dev/native-lazy-loading/) with this:
80 |
81 | ```javascript
82 | const presets = {
83 | default: {
84 | sizes: '(max-width: 45em) 90vw, 40em',
85 | attributes: {
86 | loading: 'lazy',
87 | },
88 | },
89 | logo: {
90 | sizes: '(max-width: 45em) 18vw, 8em',
91 | classes: ['logo'],
92 | },
93 | };
94 | ```
95 |
96 | _Note: The `logo` preset will inherit the `default` preset and override its common properties._
97 |
98 | If logo pristine images always have the same dimensions, we could even add them to the `logo` preset attributes:
99 |
100 | ```javascript
101 | const presets = {
102 | default: {
103 | sizes: '(max-width: 45em) 90vw, 40em',
104 | attributes: {
105 | loading: 'lazy',
106 | },
107 | },
108 | logo: {
109 | sizes: '(max-width: 45em) 18vw, 8em',
110 | classes: ['logo'],
111 | attributes: {
112 | width: '400',
113 | height: '400',
114 | },
115 | },
116 | };
117 | ```
118 |
119 | With this configuration, we can really reduce the authors work complexity, as we can see once again:
120 |
121 |
122 |
123 | _Note: If you use a [DAM](https://en.wikipedia.org/wiki/Digital_asset_management) to manage high definition source images, you could make sure the site's pristine images have always the same dimensions, `1600x1000` for example, and add them to the preset._
124 |
125 | # Now… what?
126 |
127 | _To be continued…_
128 |
--------------------------------------------------------------------------------
/docs/tutorial/04-images-dimensions/README.md:
--------------------------------------------------------------------------------
1 | | **[<< back to home](../../)** | **[< back to step 3](../03-resized-images/#readme)** |
2 |
3 | # Step 4: Images dimensions
4 |
5 | ## Run it
6 |
7 | In the folder of the tutorial step, run a clean install then build in developer mode:
8 |
9 | ```bash
10 | npm ci
11 | npm start
12 | ```
13 |
14 | Sources are in `src/` and build result is in `dist/`.
15 |
16 | ## Check the result
17 |
18 | If you open `http://localhost:8080/` in a browser, all images should be back, on all viewports! 🎉
19 |
20 | Here is a screenshot on desktop:
21 |
22 | 
23 |
24 | And here on simulated mobile:
25 |
26 | 
27 |
28 | ## How does it work?
29 |
30 | We wanted to tell the plugin about pristine images' actual widths, so that transformed HTML wouldn't include impossible widths.
31 |
32 | Why invent a new parameter for the plugin? We already have the `width` attribute in HTML, so we used it, so that the plugin can read it.
33 |
34 | To add the `width` attribute to HTML, we added it to our Markdown, thanks again to the [Markdown-it Attributes plugin](https://github.com/arve0/markdown-it-attrs) (remember the `logo` class on the logo image?).
35 |
36 | For example, we replaced this:
37 |
38 | ```markdown
39 | {.logo}
40 | ```
41 |
42 | With this:
43 |
44 | ```markdown
45 | {.logo}{width=400}
46 | ```
47 |
48 | The plugin reads the image's width from the attribute in HTML (from the HTML, really, not from the image file properties), and uses it as a maximum value for the list of resized images in HTML.
49 |
50 | If it was supposed to add a (or multiple) larger width(s), it doesn't, but it adds the pristine image's width. For example, if the plugin was supposed to generate 5 values from 320 to 1280 pixels, it would have generated this list: `[320, 560, 800, 1040, 1280]`. But the pristine image for the logo is 400 pixels wide, so the plugin generates only this shorter list: `[320, 400]`.
51 |
52 | _Note: If you fear forgetting to add a `width` attribute to some images, you can run the build in debug mode (learn [more about debugging here](/images-responsiver/eleventy-plugin-images-responsiver/debugging.html)), you'll get warnings about missing `width` attributes. Instead of `npm start`, run `DEBUG=images-responsiver:* npm start`._
53 |
54 | _Note: Specifying both `width` and `height` attributes on images helps browsers prepare the required area in the page even if the image has not yet been downloaded. It [enhances the page rendering performance](https://www.youtube.com/watch?v=4-d_SoCHeWE), and reduces [Cumulative Layout Shift](https://blog.dareboost.com/en/2020/09/cumulative-layout-shift-visual-instability/), which is very good for the user experience._
55 |
56 |
62 |
63 | # Now… what?
64 |
65 | Unfortunately, there is still an issue with this transformed HTML.
66 |
67 | Reading the transformed HTML, you might have noticed that both images' `sizes` attributes have the same value: `sizes="100vw"`. This means the browser thinks both images are supposed to be rendered on the full width of the browser's viewport.
68 |
69 | It's almost true for the big photo, at least on smallest viewports, but always really false for the logo, which is at most one fifth of the viewport.
70 |
71 | It means **the browser still downloads images much larger than necessary**.
72 |
73 | _Note: That's why the logo was visible on mobile in [step 3](../03-resized-images/#readme), because the viewport was 320 pixels wide, like the only available image. So what looked right was in fact wrong… 😅_
74 |
75 | Let's see how to fix this in **[step 5](../05-presets/#readme)**.
76 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # eleventy-plugin-images-responsiver
2 |
3 | []()
4 | [](https://www.npmjs.com/package/eleventy-plugin-images-responsiver)
5 | [](https://github.com/nhoizey/eleventy-plugin-images-responsiver/stargazers)
6 | [](https://mamot.fr/@nhoizey)
7 |
8 | `eleventy-plugin-images-responsiver` is **a simple solution for most responsive images needs with [Eleventy](https://www.11ty.dev/)**.
9 |
10 | This Eleventy plugin allows authors to **use the standard Markdown syntax for images** (``) and yet **get responsive images in the generated HTML**, with `srcset` and `sizes` attributes.
11 |
12 |
13 |
14 |
15 | - [Why does this project exist?](#why-does-this-project-exist)
16 | - [How does it work?](#how-does-it-work)
17 | - [Installation](#installation)
18 | - [Usage](#usage)
19 | - [Alternatives](#alternatives)
20 | - [Contributing](#contributing)
21 | - [License](#license)
22 | - [Authors](#authors)
23 |
24 |
25 |
26 | # Why does this project exist?
27 |
28 | As Steve Jobs [once said](https://www.youtube.com/watch?v=oeqPrUmVz-o):
29 |
30 | > You've got to start with the customer experience and run backwards to the technology.
31 |
32 | **Responsive images are one of the most difficult topics nowadays** for front end developers and content authors, they involve multiple features and syntaxes, but they are **required to provide a good performance to Web users**.
33 |
34 | Most content authors should not have to learn the complex responsive images HTML syntax, and how it is used by browsers to load the right image for current viewing context.
35 |
36 | Knowing that [`` is only required for rare advanced usages](https://cloudfour.com/thinks/dont-use-picture-most-of-the-time/), **`eleventy-plugin-images-responsiver` should be enough for most use cases**, known as Resolution Switching. Read [this article on Cloudfour's blog to know more of the theory](https://cloudfour.com/thinks/responsive-images-the-simple-way/).
37 |
38 | # How does it work?
39 |
40 | `eleventy-plugin-images-responsiver` is **the glue** between Eleventy plugin and transformations system and [`images-responsiver`](../images-responsiver/), the generic HTML transformation npm package for simple responsive images.
41 |
42 | Eleventy uses Markdown-it to transform Markdown content into HTML, and then runs the transform added by `eleventy-plugin-images-responsiver`, which calls `images-responsiver` to actually transform the HTML.
43 |
44 | > **Warning**
45 | > This plugin doesn't generate any image, it has to be used either with already existing images, a local image resizing solution (should work with the official [eleventy-img](https://www.11ty.dev/docs/plugins/image/) plugin), or a third party service ("image CDN") like Cloudinary.
46 |
47 | Learn more in [the detailed documentation](https://nhoizey.github.io/eleventy-plugin-images-responsiver/).
48 |
49 | # Installation
50 |
51 | To install and use the plugin, install it as a dev dependency in your Eleventy project:
52 |
53 | ```
54 | npm install eleventy-plugin-images-responsiver --save-dev
55 | ```
56 |
57 | # Usage
58 |
59 | Instead of jumping directly into the list of features and configuration options, let us take your hand and **guide you through a step by step tutorial** with actual examples.
60 |
61 | Let's **[start here](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/00-preparation/)**!
62 |
63 | If you already know how to use the plugin and want to **go directly to a section of the tutorial**, here are direct links:
64 |
65 | - [Step 0: Get the resources to follow this tutorial](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/00-preparation/)
66 | - [Step 1: Default behaviour without the plugin](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/01-without-plugin/)
67 | - [Step 2: Default behaviour with the plugin](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/02-with-plugin-default/)
68 | - [Step 3: Resized images](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/03-resized-images/)
69 | - [Step 4: Images dimensions](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/04-images-dimensions/)
70 | - [Step 5: Presets](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/05-presets/)
71 | - [Step 6: Presets properties](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/06-presets-properties/)
72 |
73 | # Alternatives
74 |
75 | To deal with responsive images in Eleventy, there are multiple other plugins:
76 |
77 | - [eleventy-img](https://www.11ty.dev/docs/plugins/image/) by Zach Leatherman ([@zachleat](https://twitter.com/zachleat)) is a low level utility to perform build-time image transformations for both vector and raster images, but it doesn't generateany markup
78 | - [eleventy-plugin-respimg](https://www.npmjs.com/package/eleventy-plugin-respimg) by Eric Portis ([@etportis](https://twitter.com/etportis/)) provides a shortcode for responsive images with Cloudinary
79 | - [eleventy-plugin-local-respimg](https://github.com/chromeos/static-site-scaffold-modules/tree/master/modules/eleventy-plugin-local-respimg) by Sam Richard ([@Snugug](https://twitter.com/Snugug/)) provides an Eleventy transform for resizing and optimizing local images
80 |
81 | # Contributing
82 |
83 | First, thank you for considering contributing to `eleventy-plugin-images-responsiver`! It's people like you that make the open source community such a great community! 😊
84 |
85 | There are many ways to contribute to this project. [Get started here](https://github.com/nhoizey/eleventy-plugin-images-responsiver/blob/main/CONTRIBUTING.md).
86 |
87 | # License
88 |
89 | This project is licensed under the [MIT License](LICENSE.md).
90 |
91 | # Authors
92 |
93 | - [Nicolas Hoizey](https://github.com/nhoizey): Idea and initial work, maintainer
94 |
95 | See also the list of [contributors](https://github.com/nhoizey/eleventy-plugin-images-responsiver/contributors) who participated in this project.
96 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | # eleventy-plugin-images-responsiver
2 |
3 | []()
4 | [](https://www.npmjs.com/package/eleventy-plugin-images-responsiver)
5 | [](https://github.com/nhoizey/eleventy-plugin-images-responsiver/stargazers)
6 | [](https://mamot.fr/@nhoizey)
7 |
8 | `eleventy-plugin-images-responsiver` is **a simple solution for most responsive images needs with [Eleventy](https://www.11ty.dev/)**.
9 |
10 | This Eleventy plugin allows authors to **use the standard Markdown syntax for images** (``) and yet **get responsive images in the generated HTML**, with `srcset` and `sizes` attributes.
11 |
12 |
13 |
14 |
15 | - [Why does this project exist?](#why-does-this-project-exist)
16 | - [How does it work?](#how-does-it-work)
17 | - [Installation](#installation)
18 | - [Usage](#usage)
19 | - [Alternatives](#alternatives)
20 | - [Contributing](#contributing)
21 | - [License](#license)
22 | - [Authors](#authors)
23 |
24 |
25 |
26 | # Why does this project exist?
27 |
28 | As Steve Jobs [once said](https://www.youtube.com/watch?v=oeqPrUmVz-o):
29 |
30 | > You've got to start with the customer experience and run backwards to the technology.
31 |
32 | **Responsive images are one of the most difficult topics nowadays** for front end developers and content authors, they involve multiple features and syntaxes, but they are **required to provide a good performance to Web users**.
33 |
34 | Most content authors should not have to learn the complex responsive images HTML syntax, and how it is used by browsers to load the right image for current viewing context.
35 |
36 | Knowing that [`` is only required for rare advanced usages](https://cloudfour.com/thinks/dont-use-picture-most-of-the-time/), **`eleventy-plugin-images-responsiver` should be enough for most use cases**, known as Resolution Switching. Read [this article on Cloudfour's blog to know more of the theory](https://cloudfour.com/thinks/responsive-images-the-simple-way/).
37 |
38 | # How does it work?
39 |
40 | `eleventy-plugin-images-responsiver` is **the glue** between Eleventy plugin and transformations system and [`images-responsiver`](../images-responsiver/), the generic HTML transformation npm package for simple responsive images.
41 |
42 | Eleventy uses Markdown-it to transform Markdown content into HTML, and then runs the transform added by `eleventy-plugin-images-responsiver`, which calls `images-responsiver` to actually transform the HTML.
43 |
44 | > **Warning**
45 | > This plugin doesn't generate any image, it has to be used either with already existing images, a local image resizing solution (should work with the official [eleventy-img](https://www.11ty.dev/docs/plugins/image/) plugin), or a third party service ("image CDN") like Cloudinary.
46 |
47 | Learn more in [the detailed documentation](https://nhoizey.github.io/eleventy-plugin-images-responsiver/).
48 |
49 | # Installation
50 |
51 | To install and use the plugin, install it as a dev dependency in your Eleventy project:
52 |
53 | ```
54 | npm install eleventy-plugin-images-responsiver --save-dev
55 | ```
56 |
57 | # Usage
58 |
59 | Instead of jumping directly into the list of features and configuration options, let us take your hand and **guide you through a step by step tutorial** with actual examples.
60 |
61 | Let's **[start here](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/00-preparation/)**!
62 |
63 | If you already know how to use the plugin and want to **go directly to a section of the tutorial**, here are direct links:
64 |
65 | - [Step 0: Get the resources to follow this tutorial](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/00-preparation/)
66 | - [Step 1: Default behaviour without the plugin](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/01-without-plugin/)
67 | - [Step 2: Default behaviour with the plugin](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/02-with-plugin-default/)
68 | - [Step 3: Resized images](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/03-resized-images/)
69 | - [Step 4: Images dimensions](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/04-images-dimensions/)
70 | - [Step 5: Presets](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/05-presets/)
71 | - [Step 6: Presets properties](https://nhoizey.github.io/eleventy-plugin-images-responsiver/tutorial/06-presets-properties/)
72 |
73 | # Alternatives
74 |
75 | To deal with responsive images in Eleventy, there are multiple other plugins:
76 |
77 | - [eleventy-img](https://www.11ty.dev/docs/plugins/image/) by Zach Leatherman ([@zachleat](https://twitter.com/zachleat)) is a low level utility to perform build-time image transformations for both vector and raster images, but it doesn't generateany markup
78 | - [eleventy-plugin-respimg](https://www.npmjs.com/package/eleventy-plugin-respimg) by Eric Portis ([@etportis](https://twitter.com/etportis/)) provides a shortcode for responsive images with Cloudinary
79 | - [eleventy-plugin-local-respimg](https://github.com/chromeos/static-site-scaffold-modules/tree/master/modules/eleventy-plugin-local-respimg) by Sam Richard ([@Snugug](https://twitter.com/Snugug/)) provides an Eleventy transform for resizing and optimizing local images
80 |
81 | # Contributing
82 |
83 | First, thank you for considering contributing to `eleventy-plugin-images-responsiver`! It's people like you that make the open source community such a great community! 😊
84 |
85 | There are many ways to contribute to this project. [Get started here](https://github.com/nhoizey/eleventy-plugin-images-responsiver/blob/main/CONTRIBUTING.md).
86 |
87 | # License
88 |
89 | This project is licensed under the [MIT License](LICENSE.md).
90 |
91 | # Authors
92 |
93 | - [Nicolas Hoizey](https://github.com/nhoizey): Idea and initial work, maintainer
94 |
95 | See also the list of [contributors](https://github.com/nhoizey/eleventy-plugin-images-responsiver/contributors) who participated in this project.
96 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Change Log
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | # 2.0.0
6 |
7 | - Split the monorepo into two individual repos:
8 | - [`images-responsiver`](https://github.com/nhoizey/images-responsiver/)
9 | - [`eleventy-plugin-images-responsiver`](https://github.com/nhoizey/eleventy-plugin-images-responsiver/)
10 | - Make the plugin compatible with Eleventy 2.0.0 ([9640dec](https://github.com/nhoizey/eleventy-plugin-images-responsiver/commit/9640dec298b42544e99bd27e15857e563d0b26fa))
11 |
12 | # Before 2.0.0
13 |
14 | Before release 2.0.0, version numbers were synchronized for [`images-responsiver`](https://github.com/nhoizey/images-responsiver/) and [`eleventy-plugin-images-responsiver`](https://github.com/nhoizey/eleventy-plugin-images-responsiver/).
15 |
16 | ## 1.12.0
17 |
18 | - add a sizesOverride setting to allow setting sizes attribute in the source HTML ([add0043](https://github.com/nhoizey/images-responsiver/commit/add0043ed2fbaf9e13d5a2ebf324aeea2766ff9a)), closes [#191](https://github.com/nhoizey/images-responsiver/issues/191)
19 |
20 | ## 1.11.0
21 |
22 | - support a "false" value for the data-responsiver attribute ([745d613](https://github.com/nhoizey/images-responsiver/commit/745d61398c8019bdb9876eafb1f7b50fc816c992))
23 |
24 | ## 1.10.0
25 |
26 | - add support for data-src for lazy loaded images ([c5e6f6e](https://github.com/nhoizey/images-responsiver/commit/c5e6f6e8efe84e05645b2fd8bf5d1388ce6fa739))
27 |
28 | ## 1.9.0
29 |
30 | - Replace basicHTML with LinkeDOM #138
31 | - basicHTML is deprecated, LinkeDOM recommended instead
32 | - Eleventy build with eleventy-plugin-images-responsiver is now **[approximatively 30 % faster](https://github.com/nhoizey/images-responsiver/issues/138#issuecomment-868592521)** 🎉
33 |
34 | ## 1.8.4
35 |
36 | - Update BasicHTML dependency to fix issue with inline CSS custom properties https://github.com/WebReflection/basicHTML/issues/56
37 |
38 | ## 1.8.3
39 |
40 | - Enhance basicHTML usage
41 | - Enhance docs
42 |
43 | ## 1.8.2
44 |
45 | - fix: ignores files with `permalink=false` that don't generate any HTML #90
46 | - fix: don't add a second `` tag if there's already one 98d75b7777dfc5b72603d8fdabacb85eff344f30
47 |
48 | ## 1.8.0
49 |
50 | - Upgrade basicHTML to 2.3.0 5095851880c1c9a916c41008eef009cf66a3db23
51 | - Make sure the parent is not a picture 979bad85619586fa3005227bdf9c27137dfc5ae0
52 | - Don't set twice the same image width in srcset 979bad85619586fa3005227bdf9c27137dfc5ae0
53 |
54 | ## 1.6.4
55 |
56 | - basichtml is now fixed! 👍 9211b73
57 |
58 | ## 1.6.3
59 |
60 | - Quick fix for BasicHTML issue 8ff43eb
61 |
62 | ## 1.6.2
63 |
64 | - Remove current documentation, waiting for full rewrite 1176884
65 |
66 | ## 1.6.1
67 |
68 | - Make sure people don't put a `selector` property in a preset other than default 789cabf
69 | - Add link to Cloudfour article 0dc4fb1
70 |
71 | ## 1.6.0
72 |
73 | - Add tests and organize them a26a1c4
74 | - Allow setting a list of widths instead of min and max f7787a4
75 |
76 | ## 1.5.1
77 |
78 | - Fix link to homepage 78b2673
79 | - Add debugging doc to readme 4e8eda9
80 |
81 | ## 1.5.0
82 |
83 | - Add docs about debugging ddcc735
84 | - Better default maxWidth 913bae0
85 | - Don't put images larger than pristine image in srcset e3f0cd9
86 | - Add debug dependency for better reporting of warnings c8c90fa
87 |
88 | ## 1.4.0
89 |
90 | - Split tests into several sets 29e9c65
91 | - Make sure maxWidth > minWidth 8736ebb
92 | - Make sure there are at least 2 steps for minWidth and maxWidth 1f80193
93 | - Make it clear the plugin is required when using Eleventy cfb1b59
94 |
95 | ## 1.3.1
96 |
97 | - Remove tests from the package e856e9c
98 |
99 | ## 1.3.0
100 |
101 | - Remove one useless level in settings 09ba8e8
102 |
103 | ## 1.2.2
104 |
105 | - Remove docs from npm package bf377bc
106 |
107 | ## 1.2.1
108 |
109 | - Make sure it works for images with width inferior to minWidth option 515e00d
110 |
111 | ## 1.2.0
112 |
113 | - 🐛 Make sure settings for one image are not reused for the next one a0b9a04
114 | - 🦋 Enhance example code with Prettier 97b2f3f
115 | - Add comments in scripts 79411f7
116 | - Split tutorial in several steps 6a446a8
117 | - Use clean snapshots with Prettier c19504f
118 | - Options parameter is optional 24f9f53
119 |
120 | ## 1.1.0
121 |
122 | - Prettier db4126e
123 | - Filter out images without a src, or not SVG, or with already a srcset 823ed6a
124 |
125 | ## 1.0.0
126 |
127 | - Pass document to the hooks 7eb4d36
128 | - Fine tune ESLint and Prettier configuration fedcfe6
129 | - Lint and make prettier aaa5d0a
130 |
131 | ## 0.15.0
132 |
133 | This release adds `runBefore` and `runAfter` hook methods to manipulate the image (geet data, modify it, etc.) before and after it's been "responsivised".
134 |
135 | - be strict for tests 0af2952
136 | - Upgrade BasicHTML in lock file 25da11c
137 | - Add runBefore and runAfter hook methods 39ed728
138 | - Upgrade BasicHTML module 0a95d38
139 | - Rename the example ddbcf10
140 |
141 | ## 0.14.0
142 |
143 | This release replaces JSDOM with BasicHTML to use less memory.
144 | Thanks @ziir! 🙏
145 |
146 | - Add Prettier config d57ccdb
147 | - Upgrading BasicHTML 3d0def7
148 | - Merge pull request #4 from nhoizey/pr/3 3bbd7b2
149 | - Merge pull request #3 from ziir/use-basichtml 34771bd
150 | - Fix tests 4f38a05
151 | - Use basicHTML over JSDOM 47d9f66
152 | - These should not be here a80ad35
153 |
154 | ## 0.13.2
155 |
156 | - Add a bad example for memory issue 0ea9bf4
157 | - Options can be empty 00e6851
158 | - Make sure to load the right page 0d60d4f
159 | - Arrange doccs a0f4cbd
160 | - Remove useless preset 466777a
161 |
162 | ## 0.13.1
163 |
164 | - Additional documentation 002ebbf
165 | - Simplify the example c1cd462
166 |
167 | ## 0.13.0
168 |
169 | - Add documentation 6a36911
170 | - Use the real jsdom package 8a82e9b
171 | - Rename license file bd4ce85
172 | - Update tests d4d26a6
173 | - No need for a message, this is overly verbose 6e0cba7
174 | - Why would it not work with relative URLs? 99ee24a
175 | - No need for a message, this is not a linter (bis) 0e251b7
176 | - No need for a message, this is not a linter dba53e3
177 | - This is now useless 9e00717
178 | - These settings have to be managed differently 76b33c9
179 | - Load jsdom only when needed b66964f
180 | - Try to clean memory 818a3bb
181 | - Use jsdom's serialize() method adbc94f
182 | - Use the dataset API 16a5d4a
183 | - Use the image's dataset instead of a class to define preset(s) to use 43ac9e9
184 | - Provide an example 0e83d49
185 |
186 | ## 0.12.0
187 |
188 | - Provide the main entry point 1991d2a
189 | - Remove leftovers 😅 f4e8bf1
190 |
191 | ## 0.11.0
192 |
193 | - Typo in the method name e0364f9
194 |
195 | ## 0.10.0
196 |
197 | - CSS typo ef8ad4a
198 | - Don't change images that already have a srcset attribute ef09d8b
199 |
200 | ## 0.9.0
201 |
202 | - Exit ASAP if the image can't be transformed 0937e32
203 | - Add tests for relative URL and SVG files ea97b83
204 |
205 | ## 0.8.0
206 |
207 | - Don't try anything on SVG images 76ee8e8
208 |
209 | ## 0.7.1
210 |
211 | - Typo 9407e75
212 |
213 | ## 0.7.0
214 |
215 | - More explicit messages 265a20e
216 |
--------------------------------------------------------------------------------
27 | 
22 |