Browse Source

Docs for resize_image()

index-subcmd
Vojtech Kral Vincent Prouillet 6 years ago
parent
commit
7c8d39fe9c
18 changed files with 131 additions and 2 deletions
  1. BIN
      docs/content/documentation/content/image-resizing/example-00.jpg
  2. BIN
      docs/content/documentation/content/image-resizing/example-01.jpg
  3. BIN
      docs/content/documentation/content/image-resizing/example-02.jpg
  4. BIN
      docs/content/documentation/content/image-resizing/example-03.jpg
  5. BIN
      docs/content/documentation/content/image-resizing/gutenberg.jpg
  6. +123
    -1
      docs/content/documentation/content/image-resizing/index.md
  7. +4
    -0
      docs/content/documentation/templates/overview.md
  8. +4
    -1
      docs/content/documentation/templates/pages-sections.md
  9. BIN
      docs/static/_resized_images/2e13805bc51b68e800.jpg
  10. BIN
      docs/static/_resized_images/2fa5b43d38d9f5a600.jpg
  11. BIN
      docs/static/_resized_images/5a8ef01aac8b5c8700.jpg
  12. BIN
      docs/static/_resized_images/8b0ae741aed115a800.jpg
  13. BIN
      docs/static/_resized_images/b2435b04c4bd3cb400.jpg
  14. BIN
      docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg
  15. BIN
      docs/static/_resized_images/ca684a0de40c030c00.jpg
  16. BIN
      docs/static/_resized_images/e13a85d2c34cbf6900.jpg
  17. BIN
      docs/static/_resized_images/f1f9e1ab29575d0f00.jpg
  18. BIN
      docs/static/_resized_images/f969dfdd99d2fe1500.jpg

BIN
docs/content/documentation/content/image-resizing/example-00.jpg View File

Before After
Width: 995  |  Height: 768  |  Size: 192KB

BIN
docs/content/documentation/content/image-resizing/example-01.jpg View File

Before After
Width: 1024  |  Height: 680  |  Size: 203KB

BIN
docs/content/documentation/content/image-resizing/example-02.jpg View File

Before After
Width: 420  |  Height: 600  |  Size: 42KB

BIN
docs/content/documentation/content/image-resizing/example-03.jpg View File

Before After
Width: 1024  |  Height: 617  |  Size: 250KB

BIN
docs/content/documentation/content/image-resizing/gutenberg.jpg View File

Before After
Width: 300  |  Height: 380  |  Size: 47KB

+ 123
- 1
docs/content/documentation/content/image-resizing/index.md View File

@@ -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>
&ensp;
{% 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>

+ 4
- 0
docs/content/documentation/templates/overview.md View File

@@ -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.

+ 4
- 1
docs/content/documentation/templates/pages-sections.md View File

@@ -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 View File

Before After
Width: 240  |  Height: 180  |  Size: 15KB

BIN
docs/static/_resized_images/2fa5b43d38d9f5a600.jpg View File

Before After
Width: 240  |  Height: 180  |  Size: 13KB

BIN
docs/static/_resized_images/5a8ef01aac8b5c8700.jpg View File

Before After
Width: 118  |  Height: 150  |  Size: 4.7KB

BIN
docs/static/_resized_images/8b0ae741aed115a800.jpg View File

Before After
Width: 150  |  Height: 150  |  Size: 5.5KB

BIN
docs/static/_resized_images/b2435b04c4bd3cb400.jpg View File

Before After
Width: 100  |  Height: 126  |  Size: 3.8KB

BIN
docs/static/_resized_images/b9a9fe3b3dee28cc00.jpg View File

Before After
Width: 118  |  Height: 150  |  Size: 4.7KB

BIN
docs/static/_resized_images/ca684a0de40c030c00.jpg View File

Before After
Width: 240  |  Height: 180  |  Size: 4.4KB

BIN
docs/static/_resized_images/e13a85d2c34cbf6900.jpg View File

Before After
Width: 150  |  Height: 150  |  Size: 5.5KB

BIN
docs/static/_resized_images/f1f9e1ab29575d0f00.jpg View File

Before After
Width: 240  |  Height: 180  |  Size: 18KB

BIN
docs/static/_resized_images/f969dfdd99d2fe1500.jpg View File

Before After
Width: 240  |  Height: 180  |  Size: 8.1KB

Loading…
Cancel
Save