Docs for resize_image()
BIN
docs/content/documentation/content/image-resizing/example-00.jpg
Normal file
After Width: | Height: | Size: 192 KiB |
BIN
docs/content/documentation/content/image-resizing/example-01.jpg
Normal file
After Width: | Height: | Size: 204 KiB |
BIN
docs/content/documentation/content/image-resizing/example-02.jpg
Normal file
After Width: | Height: | Size: 42 KiB |
BIN
docs/content/documentation/content/image-resizing/example-03.jpg
Normal file
After Width: | Height: | Size: 250 KiB |
BIN
docs/content/documentation/content/image-resizing/gutenberg.jpg
Normal file
After Width: | Height: | Size: 47 KiB |
|
@ -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
|
||||
<img src="{{ resize_image(path=path, width=width, height=height, op=op) }}" />
|
||||
```
|
||||
|
||||
## 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 %}
|
||||
<a href="{{ config.base_url }}/{{ img }}">
|
||||
<img src="{{ resize_image(path=img, width=240, height=180) }}" />
|
||||
</a>
|
||||
 
|
||||
{% 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() }}
|
||||
|
||||
<small>
|
||||
Image attribution: example-01: Willi Heidelbach, example-02: Daniel Ullrich, others: public domain.
|
||||
</small>
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -37,7 +37,10 @@ previous: Page?;
|
|||
next: Page?;
|
||||
// See the Table of contents section below for more details
|
||||
toc: Array<Header>;
|
||||
// TODO: add assets & assets_imgs (also draft is missing?)
|
||||
// Paths of colocated assets, relative to the content directory
|
||||
assets: Array<String>;
|
||||
// Paths of colocated image assets, ie. files with an extension of "jpg", "jpeg", "png", "gif", or "bmp"
|
||||
assets_imgs: Array<String>;
|
||||
```
|
||||
|
||||
## Section variables
|
||||
|
|
BIN
docs/static/_resized_images/2e13805bc51b68e800.jpg
vendored
Normal file
After Width: | Height: | Size: 15 KiB |
BIN
docs/static/_resized_images/2fa5b43d38d9f5a600.jpg
vendored
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
docs/static/_resized_images/5a8ef01aac8b5c8700.jpg
vendored
Normal file
After Width: | Height: | Size: 4.7 KiB |
BIN
docs/static/_resized_images/8b0ae741aed115a800.jpg
vendored
Normal file
After Width: | Height: | Size: 5.5 KiB |
BIN
docs/static/_resized_images/b2435b04c4bd3cb400.jpg
vendored
Normal file
After Width: | Height: | Size: 3.8 KiB |
BIN
docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg
vendored
Normal file
After Width: | Height: | Size: 4.7 KiB |
BIN
docs/static/_resized_images/ca684a0de40c030c00.jpg
vendored
Normal file
After Width: | Height: | Size: 4.4 KiB |
BIN
docs/static/_resized_images/e13a85d2c34cbf6900.jpg
vendored
Normal file
After Width: | Height: | Size: 5.5 KiB |
BIN
docs/static/_resized_images/f1f9e1ab29575d0f00.jpg
vendored
Normal file
After Width: | Height: | Size: 18 KiB |
BIN
docs/static/_resized_images/f969dfdd99d2fe1500.jpg
vendored
Normal file
After Width: | Height: | Size: 8.1 KiB |