diff --git a/docs/content/documentation/content/image-resizing/example-00.jpg b/docs/content/documentation/content/image-resizing/example-00.jpg new file mode 100644 index 00000000..77ed919c Binary files /dev/null and b/docs/content/documentation/content/image-resizing/example-00.jpg differ diff --git a/docs/content/documentation/content/image-resizing/example-01.jpg b/docs/content/documentation/content/image-resizing/example-01.jpg new file mode 100644 index 00000000..483a8428 Binary files /dev/null and b/docs/content/documentation/content/image-resizing/example-01.jpg differ diff --git a/docs/content/documentation/content/image-resizing/example-02.jpg b/docs/content/documentation/content/image-resizing/example-02.jpg new file mode 100644 index 00000000..6972f7a9 Binary files /dev/null and b/docs/content/documentation/content/image-resizing/example-02.jpg differ diff --git a/docs/content/documentation/content/image-resizing/example-03.jpg b/docs/content/documentation/content/image-resizing/example-03.jpg new file mode 100644 index 00000000..99837c20 Binary files /dev/null and b/docs/content/documentation/content/image-resizing/example-03.jpg differ diff --git a/docs/content/documentation/content/image-resizing/gutenberg.jpg b/docs/content/documentation/content/image-resizing/gutenberg.jpg new file mode 100644 index 00000000..0b031e9c Binary files /dev/null and b/docs/content/documentation/content/image-resizing/gutenberg.jpg differ diff --git a/docs/content/documentation/content/image-resizing/index.md b/docs/content/documentation/content/image-resizing/index.md index 30554604..81529ee2 100644 --- a/docs/content/documentation/content/image-resizing/index.md +++ b/docs/content/documentation/content/image-resizing/index.md @@ -3,6 +3,128 @@ title = "Image Resizing" weight = 120 +++ -TODO: talk about resize_image +Gutengerb provides support for automatic image resizing through the built-in function `resize_image`, +which is available in template code as well as in shortcodes. + +The function usage is as follows: + +```jinja2 + resize_image(path, width, height, op, quality) +``` + +### Arguments + +- `path`: The path to the source image relative to the `content` directory in the [directory structure](./documentation/getting-started/directory-structure.md). + +- `width` and `height`: The dimensions in pixels of the resized image. Usage depends on the `op` argument. +- `op`: Resize operation. This can be one of five choices: `"scale"`, `"fitwidth"`, `"fitheight"`, `"fit"`, or `"fill"`. + What each of these does is explained below. + This argument is optional, default value is `"fill"`. +- `quality`: JPEG quality of the resized image, in percents. Optional argument, default value is `75`. + +### Image processing and return value + +Gutenberg performs image processing during the build process and places the resized images in a subdirectory in the static files directory: + + static/_resized_images/ + +Resized images are JPEGs. Filename of each resized image is a hash of the function arguments, +which means that once an image is resized in a certain way, it will be stored in the above directory and will not +need to be resized again during subsequent builds (unless the image itself, the dimensions, or other arguments are changed). +Therefore, if you have a large number of images, they will only need to be resized once. + +The function returns a full URL to the resized image. + +## Resize operations + +The source for all examples is this 300 × 380 pixels image: + +![gutenberg](gutenberg.jpg) + +### **`"scale"`** + Simply scales the image to the specified dimensions (`width` & `height`) irrespective of the aspect ratio. + + `resize_image(..., width=150, height=150, op="scale")` + + {{ resize_image(path="documentation/content/image-resizing/gutenberg.jpg", width=150, height=150, op="scale") }} + +### **`"fitwidth"`** + Resizes the image such that the resulting width is `width` and height is whatever will preserve the aspect ratio. + The `height` argument is not needed. + + `resize_image(..., width=100, op="fitwidth")` + + {{ resize_image(path="documentation/content/image-resizing/gutenberg.jpg", width=100, height=0, op="fitwidth") }} + +### **`"fitheight"`** + Resizes the image such that the resulting height is `height` and width is whatever will preserve the aspect ratio. + The `width` argument is not needed. + + `resize_image(..., height=150, op="fitheight")` + + {{ resize_image(path="documentation/content/image-resizing/gutenberg.jpg", width=0, height=150, op="fitheight") }} + +### **`"fit"`** + Like `"fitwidth"` and `"fitheight"` combined. + Resizes the image such that the result fits within `width` and `height` preserving aspect ratio. This means that both width or height + will be at max `width` and `height`, respectively, but possibly one of them smaller so as to preserve the aspect ratio. + + `resize_image(..., width=150, height=150, op="fit")` + + {{ resize_image(path="documentation/content/image-resizing/gutenberg.jpg", width=150, height=150, op="fit") }} + +### **`"fill"`** + This is the default operation. It takes the image's center part with the same aspect ratio as the `width` & `height` given and resizes that + to `width` & `height`. This means that parts of the image that are outsize of the resized aspect ratio are cropped away. + + `resize_image(..., width=150, height=150, op="fill")` + + {{ resize_image(path="documentation/content/image-resizing/gutenberg.jpg", width=150, height=150, op="fill") }} + + +## Using `resize_image` in markdown via shortcodes + +`resize_image` is a built-in Tera global function (see the [Templates](./documentation/templates/_index.md) chapter), +but it can be used in markdown, too, using [Shortcodes](./documentation/content/shortcodes.md). + +The examples above were generated using a shortcode file named `resize_image.html` with this content: + +```jinja2 + +``` + +## Creating picuture galleries + +The `resize_image()` can be used multiple times and/or in loops (it is designed to handle this efficiently). + +This can be used along with `assets_imgs` [page metadata](./documentation/templates/pages-sections.md) to create picture galleries. +The `assets_imgs` variable holds paths to all images in the directory of a page with resources +(see [Assets colocation](./documentation/content/overview.md#assets-colocation)). + +This can be used in shortcodes. For example, we can create a very simple html-only clickable +picture gallery with the following shortcode named `gallery.html`: + +```jinja2 +{% for img in page.assets_imgs %} + + + +   +{% endfor %} +``` + +As you can notice, we didn't specify an `op` argument, which means it'll default to `"fill"`. Similarly, the JPEG quality will default to `75`. + +To call it from a markdown file, simply do: + +```jinja2 +{{/* gallery() */}} +``` + +Here is the result: {{ gallery() }} + + + Image attribution: example-01: Willi Heidelbach, example-02: Daniel Ullrich, others: public domain. + diff --git a/docs/content/documentation/templates/overview.md b/docs/content/documentation/templates/overview.md index f843059d..6b88a98f 100644 --- a/docs/content/documentation/templates/overview.md +++ b/docs/content/documentation/templates/overview.md @@ -105,3 +105,7 @@ Gets the translation of the given `key`, for the `default_language` or the `lang {{/* trans(key="title") */}} {{/* trans(key="title", lang="fr") */}} ``` + +### `resize_image` +Resizes an image file. +Pease refer to [_Content / Image Resizing_](./documentation/content/image-resizing/index.md) for complete documentation. diff --git a/docs/content/documentation/templates/pages-sections.md b/docs/content/documentation/templates/pages-sections.md index 7c90a803..a4848b32 100644 --- a/docs/content/documentation/templates/pages-sections.md +++ b/docs/content/documentation/templates/pages-sections.md @@ -37,7 +37,10 @@ previous: Page?; next: Page?; // See the Table of contents section below for more details toc: Array
; -// TODO: add assets & assets_imgs (also draft is missing?) +// Paths of colocated assets, relative to the content directory +assets: Array; +// Paths of colocated image assets, ie. files with an extension of "jpg", "jpeg", "png", "gif", or "bmp" +assets_imgs: Array; ``` ## Section variables diff --git a/docs/static/_resized_images/2e13805bc51b68e800.jpg b/docs/static/_resized_images/2e13805bc51b68e800.jpg new file mode 100644 index 00000000..aa7f148e Binary files /dev/null and b/docs/static/_resized_images/2e13805bc51b68e800.jpg differ diff --git a/docs/static/_resized_images/2fa5b43d38d9f5a600.jpg b/docs/static/_resized_images/2fa5b43d38d9f5a600.jpg new file mode 100644 index 00000000..fe24b2ab Binary files /dev/null and b/docs/static/_resized_images/2fa5b43d38d9f5a600.jpg differ diff --git a/docs/static/_resized_images/5a8ef01aac8b5c8700.jpg b/docs/static/_resized_images/5a8ef01aac8b5c8700.jpg new file mode 100644 index 00000000..4d009ddf Binary files /dev/null and b/docs/static/_resized_images/5a8ef01aac8b5c8700.jpg differ diff --git a/docs/static/_resized_images/8b0ae741aed115a800.jpg b/docs/static/_resized_images/8b0ae741aed115a800.jpg new file mode 100644 index 00000000..f07aed33 Binary files /dev/null and b/docs/static/_resized_images/8b0ae741aed115a800.jpg differ diff --git a/docs/static/_resized_images/b2435b04c4bd3cb400.jpg b/docs/static/_resized_images/b2435b04c4bd3cb400.jpg new file mode 100644 index 00000000..b25d734c Binary files /dev/null and b/docs/static/_resized_images/b2435b04c4bd3cb400.jpg differ diff --git a/docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg b/docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg new file mode 100644 index 00000000..4d009ddf Binary files /dev/null and b/docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg differ diff --git a/docs/static/_resized_images/ca684a0de40c030c00.jpg b/docs/static/_resized_images/ca684a0de40c030c00.jpg new file mode 100644 index 00000000..5156b37c Binary files /dev/null and b/docs/static/_resized_images/ca684a0de40c030c00.jpg differ diff --git a/docs/static/_resized_images/e13a85d2c34cbf6900.jpg b/docs/static/_resized_images/e13a85d2c34cbf6900.jpg new file mode 100644 index 00000000..bb6fc4a7 Binary files /dev/null and b/docs/static/_resized_images/e13a85d2c34cbf6900.jpg differ diff --git a/docs/static/_resized_images/f1f9e1ab29575d0f00.jpg b/docs/static/_resized_images/f1f9e1ab29575d0f00.jpg new file mode 100644 index 00000000..bc601ba7 Binary files /dev/null and b/docs/static/_resized_images/f1f9e1ab29575d0f00.jpg differ diff --git a/docs/static/_resized_images/f969dfdd99d2fe1500.jpg b/docs/static/_resized_images/f969dfdd99d2fe1500.jpg new file mode 100644 index 00000000..89e7b58c Binary files /dev/null and b/docs/static/_resized_images/f969dfdd99d2fe1500.jpg differ