From b965c89d12689d658a70f67f78d9de76b1a1cf48 Mon Sep 17 00:00:00 2001
From: Jonas Diemer <jonasdiemer@gmail.com>
Date: Sat, 15 Jun 2024 23:08:40 +0200
Subject: [PATCH] Added documentation about relative image resizing and scaling
 of high-res (#2096)

---
 .../content/image-processing/index.md         | 32 ++++++++++++++++++-
 docs/templates/shortcodes/high_res_image.html |  5 +++
 .../shortcodes/resize_image_relative.html     |  3 ++
 3 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 docs/templates/shortcodes/high_res_image.html
 create mode 100644 docs/templates/shortcodes/resize_image_relative.html

diff --git a/docs/content/documentation/content/image-processing/index.md b/docs/content/documentation/content/image-processing/index.md
index 4acffe761..c04e46d98 100644
--- a/docs/content/documentation/content/image-processing/index.md
+++ b/docs/content/documentation/content/image-processing/index.md
@@ -179,7 +179,37 @@ Here is the result:
 </small>
 
 
-## Get image size
+## Get image size and relative resizing
 
 Sometimes when building a gallery it is useful to know the dimensions of each asset.  You can get this information with
 [get_image_metadata](@/documentation/templates/overview.md#get-image-metadata).
+
+This can also be useful in combination with `resize_image()` to do a relative resizing. So we can create a relative image resizing function with the following shortcode named `resize_image_relative.html`:
+
+```jinja2
+{% set mdata = get_image_metadata(path=path) %}
+{% set image = resize_image(path=path, width=(mdata.width * scale)|int, op="fit_width") %}
+<img src="{{ image.url }}" />
+```
+
+It can be invoked from Markdown like this:
+
+`resize_image_relative(..., scale=0.5)`
+
+{{ resize_image_relative(path="documentation/content/image-processing/01-zola.png", scale=0.5) }}
+
+## Creating scaled-down versions of high-resolution images
+
+With the above, we can also create a shortcode that creates a 50% scaled-down version of a high-resolution image (e.g. screenshots taken on Retina Macs), along with the proper HTML5 `srcset` for the original image to be displayed on high-resolution / retina displays.
+
+Consider the following shortcode named `high_res_image.html`:
+
+```jinja2
+{% set mdata = get_image_metadata(path=path) %}
+{% set w = (mdata.width / 2) | int %}
+{% set h = (mdata.height / 2) | int %}
+{% set image = resize_image(path=path, width=w, height=h, op="fit_width") %}
+<img src="{{ image.url }}" srcset="/{{path}} 2x"/>
+```
+
+{{ high_res_image(path="documentation/content/image-processing/08-example.jpg") }}
diff --git a/docs/templates/shortcodes/high_res_image.html b/docs/templates/shortcodes/high_res_image.html
new file mode 100644
index 000000000..22109ef82
--- /dev/null
+++ b/docs/templates/shortcodes/high_res_image.html
@@ -0,0 +1,5 @@
+{% set mdata = get_image_metadata(path=path) %}
+{% set w = (mdata.width / 2) | int %}
+{% set h = (mdata.height / 2) | int %}
+{% set image = resize_image(path=path, width=w, height=h, op="fit_width") %}
+<img src="{{ image.url }}" srcset="/{{path}} 2x"/>
\ No newline at end of file
diff --git a/docs/templates/shortcodes/resize_image_relative.html b/docs/templates/shortcodes/resize_image_relative.html
new file mode 100644
index 000000000..fc152880f
--- /dev/null
+++ b/docs/templates/shortcodes/resize_image_relative.html
@@ -0,0 +1,3 @@
+{% set mdata = get_image_metadata(path=path) %}
+{% set image = resize_image(path=path, width=(mdata.width * scale)|int, op="fit_width") %}
+<img src="{{ image.url }}" />
\ No newline at end of file