Adds more detailed documentation for adding new images to the gallery

[tannerdolby]

It was pointed out by @ljc-dev on twitter today that its a bit unclear on what sizes and formats the images need to be in before adding them to _data/gallery.json as an object.

In total: 4 pictures

1. Original picture (intrinsic size - probably bigger than 1024px)
2. Large .webp source (1024px)
3. Medium .webp source (640px)
4. Small .webp source (320px)
5. Large .jpg source (1024px) or just use the original picture

Note:

• For ease of use, the fallback img src can be whatever size as the browser will most likely be able to support the .webp sources. But use the 1024px large source for best results.

I recommend including a image-name-large.jpg format as the src for the fallback <img> in case the .webp sources cannot be used.

Removes the following srcSet from the fallback <img> inside <picture>. Applying this update to feature.njk and base.njk.

Clear things up about usage:

1. Get an image from somewhere (your file system, a stock photo website, etc)
2. Add the original image to the /images/ folder.
3. Go into .eleventy.js and utilize sharpImages("/images/image-name.jpg")
   • This creates three resized images from the original, which outputs to the /images/ folder:
     • image-name-large.webp (1024px, 768px)
     • image-name-med.webp (640px, 480px)
     • image-name-small.webp (320px, 240px)
   • I have the image formats for this function set to .webp but the sharp package has many options (I think .avif is supported)
4. If you don't use the above method, just head over to squoosh.app and create the three resized versions from your original (1024px, 640px, 320px) and the height will be calculated based on the original image aspect ratio.
5. Include the images in /images/ if you create the resized images externally.
6. Go into _data/gallery.json and create a new object with the image metadata (This is the last step)

Filename: _data/gallery.json

{
        "title": "Terrace with green plants on night street",
        "date": "October 20, 2020",
        "credit": "Photo by Aldiyar Seitkassymov",
        "linkToAuthor": "https://www.pexels.com/photo/terrace-with-green-plants-on-night-street-3100835/",
        "imageData": {
            "alt": "Terrace outside shop window with green plants and pink tree on night street",
            "large": {
                "webp": "/images/shop-plants-large.webp",
                "jpg": "/images/shop-plants-large.jpg",
                "width": "1024w"
            },
            "medium": {
                "webp": "/images/shop-plants-med.webp",
                "width": "640w"
            },
            "small": {
                "webp": "/images/shop-plants-small.webp",
                "width": "320w"
            }
        }
    }

The image is now added to the site and you can view it by running npm run build and npm run serve

[tannerdolby]

I've updated the README.md and CONTRIBUTING.md file to include better documentation on adding new images to the gallery. Let me know if it's still unclear and if not I will close this issue.

[nhoizey]

I believe JPEG is still mandatory as 15% of Web users still don't have WebP support: https://caniuse.com/webp

[tannerdolby]

@nhoizey Thanks for the info. I still have the fallback <img> using a JPEG as its src so that should be sufficient right?

I removed the srcSet and sizes attributes for the <picture>'s fallback <img> if the .webp sources aren't supported by that users browser.

<picture>
    <source type="image/webp" ...>
    <img 
        src="{{ image.imageData.large.jpg }}"
        alt="{{ image.imageData.alt }}"
</picture>

Using a <source> tag to include the large, medium and small .webp images and using a JPEG as the last resort inside the fallback <img> src.

If the browser can't support .webp, the photo-name-large.jpg would be image on the page which doesn't perform with the same responsiveness (as it doesn't use a srcSet or sizes). This might need to be tested or revisited to update the fallback image's responsiveness if indeed the webp <source>isn't supported.

If I include a srcSet for the fallback image then the person using the template will have to create 3 resized JPEG and 3 resized webp formats (where currently it's just 4 images so a little less work converting).

[nhoizey]

I think 15 % is still a population large enough to justify srcset with multiple JPEG widths.

At least, if you don't have this srcset, you should use a smaller JPEG fallback, IMHO.

All of this would be easier if people didn't have to generate the multiple formats and widths themselves, of course. There are multiple solutions to automate this.

I made eleventy-plugin-images-responsiver to generate the HTML code, but it doesn't automate image resizing and format transformation. I use it with Cloudinary, others use it with Netlify Large Media, and I plan to try (and document) at least Imgix, Image Engine and TwicPics. But it can also be used with local transformations, with sharp for example.

[tannerdolby]

I think 15 % is still a population large enough to justify srcset with multiple JPEG widths.

Yes, I agree. I'm going to revert back the documentation and global data to include large/med/sm .jpg formats to use <img srcSet=""> and support that 15% percent that might not be able to view the .webp images.

I would like to use sharp for local transformations of image format and resizing to get rid of making users generate multiple formats and widths themselves. The current setup of forcing users to generate multiple formats and widths needs to be automated.

I will have a look at eleventy-plugin-images-responsiver and research a bit more local transformations with sharp. Thanks for the feedback!

[nhoizey]

You're welcome!

[tannerdolby]

I believe JPEG is still mandatory as 15% of Web users still don't have WebP support: https://caniuse.com/webp

I've added srcSet with JPEG image formats back to the fallback <img> if WebP isn't supported. This will provide that 15% of users without access to .webp a much better viewing experience with appropriately sized .jpg images.

FIX: commit 8b4fd35