Image optimization step in site generation

[pepinho24]

Description

Some images in the documentation are not optimized and lower the PageScore of the page, especially on mobile devices and slower or metered internet connections. Part of #110

Possible solutions

The considered approaches are described in detail in this comment

Preferred solution

After discussions and meetings, the agreed approach is using the TinyPNG API because it provides the best compression to quality ratio.

Implementation

A test project for the local optimization of the images in a documentation repository is available in TinyPngCompressor repository.

Remaining tasks

• Cross-platform easy to use solution added in docs-seed repo. E.g. a ruby and node.js scripts that can be used on Windows, MacOS and Linux. If a cross-platform solution is not possible, a build could be created that could run for each documentation based on repository passed as parameter.

Due to the TinyPNG compression algorithm, an optimized image needs to be flagged in order to avoid double optimization, which is introducing some difficulties on the cross-platform aspect.

• Optional solution for repository automatization that will verify/optimize images on push or regularly(e.g. weekly,monthly), e.g. based on GitHub Actions

[pepinho24]

Suggested plan of action

We can leverage a semi-automatic approach for the initial optimization of the biggest images using the TinyPNG API. Then, we can use the Github Actions to take care of the continuous optimization of images in the repository.

Full details of each approach

Here are some thoughts and details about the additional approaches after the analysis. To keep the comment visibly short, the details for each approach is in a collapsible section, click on the summary to expand it.

Github Actions

[Preferred]- Triggered on push in repository, creates a pull request with the optimized images

Details

• Uses this free action - https://github.com/calibreapp/image-actions
  • uses sharp.js for optimization - https://github.com/lovell/sharp
• Example
  • https://github.com/telerik/ajax-docs/blob/image-optimization/.github/workflows/calibreapp-image-actions.yml
  • https://github.com/telerik/ajax-docs/actions/runs/548589398
  • https://github.com/telerik/ajax-docs/runs/1856331687?check_suite_focus=true

Implementation

• Per repository - create a workflow yml file as in https://github.com/telerik/ajax-docs/tree/master/.github/workflows
  • might require adding a repository Secret key to overcome GitHub API limit for the initial image optimization

Pros

• Always keep optimized images in repo, hence in the live site
• Takes care of new and edited images pushed to the repository

Cons

• supports only jpg, jpeg, png => gif and bmp are not optimized
• visual quality decrease compared to TinyPNG optimization

TinyPNG

Use TinyPNG API to optimize existing images

Details

• Use TinyPNG for optimization - https://tinypng.com/developers.
• If the biggest 500 images per repository are optimized, the rest of the images will be less than 60KB => most images do not need heavy optimization

Implementation

1. Per repository - Create an account at TinyPNG to obtain the API key
2. Use the script provided by docs-seed(not available yet, will be if needed) and replace the images with optimized
3. Commit the optimized images to the repository

Pros

• Best compression rate
• Best compressed image quality

Cons

• Supports only jpg and png => gif and bmp are not optimized
• Requires an account with TinyPNG
  • Might include charges for larger amount of images

Jekyll build step

Use ruby gems to optimize images on `jekyll build`

Details

A Jekyll build step that will optimize the images on each build. This will ensure all images are optimized on the live site regardless if they are uploaded optimized in the documentation repository. An alternative is to have a separate build that will go over the generated site and optimize the images just before deploying to the live server.

Resources for a Jekyll build step:

• https://github.com/valerijaspasojevic/jekyll-compress-images
• https://rubygems.org/gems/jekyll-compress-images/versions/1.2
• https://stackoverflow.com/questions/55923556/how-do-i-compress-photos-for-my-jekyll-website
• https://matthiasruhland.com/blog/speeding-up-jekyll
• https://web.dev/use-imagemin-to-compress-images/
• Use a gem such as https://github.com/valerijaspasojevic/jekyll-compress-images to compress images

Implementation

• Enable gem in docs-seed

Pros

• Supports jpg, png and gif

Cons

• Incompatible with our Jekyll and Ruby versions
• Runs on each build =>
  • increases build time
  • optimizes an image over and over
    • unless we keep a "cache" list of optimized images in the repo itself (can easily become outdated and need a manual update)

NPM package/Grunt task

Use a Grunt task to optimize images before or after `jekyll build`

Details

• Use Grunt task as implemented here https://github.com/edrohler/GruntImageOptimizer
  • uses imagemin NPM package - https://www.npmjs.com/package/imagemin
• Possible to use via a script for initial one-time optimization to commit and keep optimized images in repo
  • https://github.com/imagemin/imagemin-cli

Implementation

• introduce node.js dependency

Pros

• supports jpg, png and gif

Cons

• Requires additional dependencies
• Runs on each build =>
  • increases build time
  • optimizes an image over and over
    • unless we keep a "cache" list of optimized images in the repo itself (can easily become outdated and need a manual update)