docs: Update image processing

This commit is contained in:
Vojtech Kral 2018-12-28 01:35:12 +01:00
parent 9bd6a559c1
commit 5348e6452e
33 changed files with 32 additions and 19 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 324 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 357 KiB

View file

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

View file

Before

Width:  |  Height:  |  Size: 192 KiB

After

Width:  |  Height:  |  Size: 192 KiB

View file

Before

Width:  |  Height:  |  Size: 204 KiB

After

Width:  |  Height:  |  Size: 204 KiB

View file

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

View file

Before

Width:  |  Height:  |  Size: 250 KiB

After

Width:  |  Height:  |  Size: 250 KiB

View file

@ -16,10 +16,22 @@ resize_image(path, width, height, op, quality)
- `path`: The path to the source image relative to the `content` directory in the [directory structure](./documentation/getting-started/directory-structure.md). - `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. - `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"`, `"fit_width"`, `"fit_height"`, `"fit"`, or `"fill"`. - `op` (_optional_): Resize operation. This can be one of:
What each of these does is explained below. - `"scale"`
This argument is optional, default value is `"fill"`. - `"fit_width"`
- `quality`: JPEG quality of the resized image, in percents. Optional argument, default value is `75`. - `"fit_height"`
- `"fit"`
- `"fill"`
What each of these does is explained below. The default is `"fill"`.
- `format` (_optional_): Encoding format of the resized image. May be one of:
- `"auto"`
- `"jpg"`
- `"png"`
The default is `"auto"`, this means the format is chosen based on input image format.
JPEG is chosen for JPEGs and other lossy formats, while PNG is chosen for PNGs and other lossless formats.
- `quality` (_optional_): JPEG quality of the resized image, in percents. Only used when encoding JPEGs, default value is `75`.
### Image processing and return value ### Image processing and return value
@ -29,7 +41,7 @@ Zola performs image processing during the build process and places the resized i
static/processed_images/ static/processed_images/
``` ```
Resized images are JPEGs. Filename of each resized image is a hash of the function arguments, 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 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). 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. Therefore, if you have a large number of images, they will only need to be resized once.
@ -40,14 +52,14 @@ The function returns a full URL to the resized image.
The source for all examples is this 300 × 380 pixels image: The source for all examples is this 300 × 380 pixels image:
![gutenberg](gutenberg.jpg) ![zola](01-zola.png)
### **`"scale"`** ### **`"scale"`**
Simply scales the image to the specified dimensions (`width` & `height`) irrespective of the aspect ratio. 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(..., width=150, height=150, op="scale")`
{{ resize_image(path="documentation/content/image-processing/gutenberg.jpg", width=150, height=150, op="scale") }} {{ resize_image(path="documentation/content/image-processing/01-zola.png", width=150, height=150, op="scale") }}
### **`"fit_width"`** ### **`"fit_width"`**
Resizes the image such that the resulting width is `width` and height is whatever will preserve the aspect ratio. Resizes the image such that the resulting width is `width` and height is whatever will preserve the aspect ratio.
@ -55,7 +67,7 @@ The source for all examples is this 300 × 380 pixels image:
`resize_image(..., width=100, op="fit_width")` `resize_image(..., width=100, op="fit_width")`
{{ resize_image(path="documentation/content/image-processing/gutenberg.jpg", width=100, height=0, op="fit_width") }} {{ resize_image(path="documentation/content/image-processing/01-zola.png", width=100, height=0, op="fit_width") }}
### **`"fit_height"`** ### **`"fit_height"`**
Resizes the image such that the resulting height is `height` and width is whatever will preserve the aspect ratio. Resizes the image such that the resulting height is `height` and width is whatever will preserve the aspect ratio.
@ -63,7 +75,7 @@ The source for all examples is this 300 × 380 pixels image:
`resize_image(..., height=150, op="fit_height")` `resize_image(..., height=150, op="fit_height")`
{{ resize_image(path="documentation/content/image-processing/gutenberg.jpg", width=0, height=150, op="fit_height") }} {{ resize_image(path="documentation/content/image-processing/01-zola.png", width=0, height=150, op="fit_height") }}
### **`"fit"`** ### **`"fit"`**
Like `"fit_width"` and `"fit_height"` combined. Like `"fit_width"` and `"fit_height"` combined.
@ -72,7 +84,7 @@ The source for all examples is this 300 × 380 pixels image:
`resize_image(..., width=150, height=150, op="fit")` `resize_image(..., width=150, height=150, op="fit")`
{{ resize_image(path="documentation/content/image-processing/gutenberg.jpg", width=150, height=150, op="fit") }} {{ resize_image(path="documentation/content/image-processing/01-zola.png", width=150, height=150, op="fit") }}
### **`"fill"`** ### **`"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 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
@ -80,7 +92,7 @@ The source for all examples is this 300 × 380 pixels image:
`resize_image(..., width=150, height=150, op="fill")` `resize_image(..., width=150, height=150, op="fill")`
{{ resize_image(path="documentation/content/image-processing/gutenberg.jpg", width=150, height=150, op="fill") }} {{ resize_image(path="documentation/content/image-processing/01-zola.png", width=150, height=150, op="fill") }}
## Using `resize_image` in markdown via shortcodes ## Using `resize_image` in markdown via shortcodes
@ -96,11 +108,11 @@ The examples above were generated using a shortcode file named `resize_image.htm
## Creating picture galleries ## Creating picture galleries
The `resize_image()` can be used multiple times and/or in loops as it is designed to handle this efficiently. 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` [page metadata](./documentation/templates/pages-sections.md) to create picture galleries. This can be used along with `assets` [page metadata](./documentation/templates/pages-sections.md) to create picture galleries.
The `assets` variable holds paths to all assets in the directory of a page with resources The `assets` variable holds paths to all assets in the directory of a page with resources
(see [Assets colocation](./documentation/content/overview.md#assets-colocation)): if you have files other than images you (see [assets colocation](./documentation/content/overview.md#assets-colocation)): if you have files other than images you
will need to filter them out in the loop first like in the example below. will need to filter them out in the loop first like in the example below.
This can be used in shortcodes. For example, we can create a very simple html-only clickable This can be used in shortcodes. For example, we can create a very simple html-only clickable
@ -108,7 +120,7 @@ picture gallery with the following shortcode named `gallery.html`:
```jinja2 ```jinja2
{% for asset in page.assets %} {% for asset in page.assets %}
{% if asset is ending_with(".jpg") %} {% if asset is matching("[.](jpg|png)$") %}
<a href="{{ get_url(path=asset) }}"> <a href="{{ get_url(path=asset) }}">
<img src="{{ resize_image(path=asset, width=240, height=180, op="fill") }}" /> <img src="{{ resize_image(path=asset, width=240, height=180, op="fill") }}" />
</a> </a>
@ -117,7 +129,8 @@ picture gallery with the following shortcode named `gallery.html`:
{% endfor %} {% 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`. As you can notice, we didn't specify an `op` argument, which means it'll default to `"fill"`. Similarly, the format will default to
`"auto"` (choosing PNG or JPEG as appropriate) and the JPEG quality will default to `75`.
To call it from a markdown file, simply do: To call it from a markdown file, simply do:
@ -130,5 +143,5 @@ Here is the result:
{{ gallery() }} {{ gallery() }}
<small> <small>
Image attribution: example-01: Willi Heidelbach, example-02: Daniel Ullrich, others: public domain. Image attribution: Public domain, except: _06-example.jpg_: Willi Heidelbach, _07-example.jpg_: Daniel Ullrich.
</small> </small>

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

View file

@ -1,7 +1,7 @@
{% for asset in page.assets -%} {% for asset in page.assets -%}
{%- if asset is ending_with(".jpg") -%} {%- if asset is matching("[.](jpg|png)$") -%}
<a href="{{ get_url(path=asset) | safe }}"> <a href="{{ get_url(path=asset) | safe }}" target="_blank">
<img src="{{ resize_image(path=asset, width=240, height=180, op="fill") | safe }}" /> <img src="{{ resize_image(path=asset, width=240, height=180, op="fill", format="auto") | safe }}" />
</a> </a>
&ensp; &ensp;
{%- endif %} {%- endif %}