summaryrefslogtreecommitdiffstats
path: root/docs/content
diff options
context:
space:
mode:
authorBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2022-03-26 11:04:57 +0200
committerBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2022-03-26 11:04:57 +0200
commitd7497b28c17fe2f402accde45c75642ed7f09d08 (patch)
treeec560802471331c111fb1fec0fd639509c50560d /docs/content
parent94459680ba391275ac667407627cafdab5a50d79 (diff)
parentd276e901b36d2576ef8350ed96b17f66254eac1b (diff)
Diffstat (limited to 'docs/content')
-rw-r--r--docs/content/en/about/security-model/index.md2
-rw-r--r--docs/content/en/content-management/diagrams.md2
-rw-r--r--docs/content/en/content-management/formats.md7
-rw-r--r--docs/content/en/content-management/image-processing/index.md436
-rw-r--r--docs/content/en/content-management/related.md6
-rw-r--r--docs/content/en/content-management/urls.md1
-rw-r--r--docs/content/en/contribute/development.md2
-rw-r--r--docs/content/en/functions/anchorize.md14
-rw-r--r--docs/content/en/functions/append.md5
-rw-r--r--docs/content/en/functions/apply.md10
-rw-r--r--docs/content/en/functions/group.md6
-rw-r--r--docs/content/en/functions/hugo.md7
-rw-r--r--docs/content/en/functions/relurl.md5
-rw-r--r--docs/content/en/functions/strings.Count.md8
-rw-r--r--docs/content/en/getting-started/configuration-markup.md116
-rw-r--r--docs/content/en/getting-started/configuration.md16
-rw-r--r--docs/content/en/getting-started/installing.md2
-rw-r--r--docs/content/en/hosting-and-deployment/deployment-with-rsync.md11
-rw-r--r--docs/content/en/showcase/over/index.md2
-rw-r--r--docs/content/en/templates/lists.md2
-rw-r--r--docs/content/en/templates/partials.md4
-rw-r--r--docs/content/en/templates/render-hooks.md172
-rw-r--r--docs/content/en/templates/template-debugging.md4
-rw-r--r--docs/content/en/variables/shortcodes.md6
24 files changed, 500 insertions, 346 deletions
diff --git a/docs/content/en/about/security-model/index.md b/docs/content/en/about/security-model/index.md
index c7e9d35c6..461c7fe77 100644
--- a/docs/content/en/about/security-model/index.md
+++ b/docs/content/en/about/security-model/index.md
@@ -42,7 +42,7 @@ The default configuration is listed below. Any build using features not in the a
Note that these and other config settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
```
-HUGO_SECURITY_HTTP_URLS=none hugo
+HUGO_SECURITY_HTTP_URLS=none hugo
```
## Dependency Security
diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md
index cfc0b3644..243a70fd4 100644
--- a/docs/content/en/content-management/diagrams.md
+++ b/docs/content/en/content-management/diagrams.md
@@ -17,7 +17,7 @@ toc: true
## GoAT Diagrams (Ascii)
-Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
+Hugo! supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
````
```goat
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
index 1ae20ba58..3c3edfdd4 100644
--- a/docs/content/en/content-management/formats.md
+++ b/docs/content/en/content-management/formats.md
@@ -4,7 +4,6 @@ linktitle: Content Formats
description: Both HTML and Markdown are supported content formats.
date: 2017-01-10
publishdate: 2017-01-10
-lastmod: 2017-04-06
categories: [content management]
keywords: [markdown,asciidoc,mmark,pandoc,content format]
menu:
@@ -27,20 +26,19 @@ You can put any file type into your `/content` directories, but Hugo uses the `m
The current list of content formats in Hugo:
-| Name | Markup identifiers | Comment |
+| Name | Markup identifiers | Comment |
| ------------- | ------------- |-------------|
| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} |
| Blackfriday | blackfriday |Blackfriday will eventually be deprecated.|
|MMark|mmark|Mmark is deprecated and will be removed in a future release.|
|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).|
|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.|
-|RST|rst|Needs [RST](http://docutils.sourceforge.net/rst.html) installed.|
+|RST|rst|Needs [RST](https://docutils.sourceforge.net/rst.html) installed.|
|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.|
|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
-
## External Helpers
Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,
@@ -149,7 +147,6 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
[mdguide]: https://www.markdownguide.org/
[mdtutorial]: https://www.markdowntutorial.com/
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
-[mmark]: https://github.com/mmarkdown/mmark
[org]: https://orgmode.org/
[pandoc]: https://www.pandoc.org/
[rest]: https://docutils.sourceforge.io/rst.html
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md
index 5b8293675..710c260ca 100644
--- a/docs/content/en/content-management/image-processing/index.md
+++ b/docs/content/en/content-management/image-processing/index.md
@@ -1,8 +1,7 @@
---
title: "Image Processing"
-description: "Image Page resources can be resized and cropped."
+description: "Resize, crop, rotate, filter, and convert images."
date: 2018-01-24T13:10:00-05:00
-linktitle: "Image Processing"
categories: ["content management"]
keywords: [resources, images]
weight: 4004
@@ -13,237 +12,334 @@ menu:
parent: "content-management"
weight: 32
---
+## Image Resources
-## The Image Page Resource
+To process an image, you must access the image as either a page resource or a global resource.
-The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below do not work on images inside your `/static` folder.
+### Page Resources
-To print all images paths in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}):
+A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
+
+```text
+content/
+└── posts/
+ └── post-1/ <-- page bundle
+ ├── index.md
+ └── sunset.jpg <-- page resource
+```
+
+To access an image as a page resource:
```go-html-template
-{{ with .Resources.ByType "image" }}
-{{ range . }}
-{{ .RelPermalink }}
-{{ end }}
-{{ end }}
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+```
+
+### Global Resources
+
+A global resource is a file:
+
+- Within the `assets` directory, or
+- Within any directory [mounted] to the `assets` directory, or
+- Located on a remote server accessible via `http` or `https`
+
+```text
+assets/
+└── images/
+ └── sunset.jpg <-- global resource
+```
+
+To access a local image as a global resource:
+```go-html-template
+{{ $image := resources.Get "images/sunset.jpg" }}
+```
+
+To access a remote image as a global resource:
+
+```go-html-template
+{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
+```
+
+## Image Rendering
+
+Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties.
+
+Example 1: Throws an error if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
```
-## The Image Resource
+Example 2: Skips image rendering if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+{{ with $image }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
-The `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}})
+Example 3: A more concise way to skip image rendering if the resource is not found.
```go-html-template
-{{- $image := resources.Get "images/logo.jpg" -}}
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
```
## Image Processing Methods
-The `image` resource implements the `Resize`, `Fit`, `Fill`, `Crop`, and `Filter` methods, each returning a transformed image using the specified dimensions and processing options.
+The `image` resource implements the `Resize`, `Fit`, `Fill`, `Crop`, `Filter`, and `Exif` methods.
{{% note %}}
-Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`](#exif) method with the _original_ image to extract EXIF metadata from JPEG or TIFF images.
+Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the`Exif` method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
{{% /note %}}
### Resize
-Resizes the image to the specified width and height.
+Resize an image to the specified width and/or height.
+
+If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
-```go
-// Resize to a width of 600px and preserve ratio
-{{ $image := $resource.Resize "600x" }}
+```go-html-template
+{{/* Resize to a width of 600px and preserve aspect ratio */}}
+{{ $image := $image.Resize "600x" }}
-// Resize to a height of 400px and preserve ratio
-{{ $image := $resource.Resize "x400" }}
+{{/* Resize to a height of 400px and preserve aspect ratio */}}
+{{ $image := $image.Resize "x400" }}
-// Resize to a width 600px and a height of 400px
-{{ $image := $resource.Resize "600x400" }}
+{{/* Resize to a width of 600px and a height of 400px */}}
+{{ $image := $image.Resize "600x400" }}
```
### Fit
-Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required.
+Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.
-```go
-{{ $image := $resource.Fit "600x400" }}
+```go-html-template
+{{ $image := $image.Fit "600x400" }}
```
### Fill
-Crop and resize the image to match the given dimensions. Both height and width are required.
+Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
-```go
-{{ $image := $resource.Fill "600x400" }}
+```go-html-template
+{{ $image := $image.Fill "600x400" }}
```
### Crop
-Crop the image to match the given dimensions without resizing. Both height and width are required.
+Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
-```go
-{{ $image := $resource.Crop "400x400" }}
+```go-html-template
+{{ $image := $image.Crop "600x400" }}
```
### Filter
-Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list.
+Apply one or more [filters] to an image.
```go-html-template
-{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
+{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
```
-The above can also be written in a more functional style using pipes:
+Write this in a more functional style using pipes. Hugo applies the filters in the order given.
```go-html-template
-{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
+{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
```
-The filters will be applied in the given order.
-
-Sometimes it can be useful to create the filter chain once and then reuse it:
+Sometimes it can be useful to create the filter chain once and then reuse it.
```go-html-template
{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }}
-{{ $img1 = $img1.Filter $filters }}
-{{ $img2 = $img2.Filter $filters }}
+{{ $image1 := $image1.Filter $filters }}
+{{ $image2 := $image2.Filter $filters }}
```
### Exif
-Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image.
+Provides an [Exif] object containing image metadata.
-Note that this is only supported for JPEG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.:
+You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a `with` statement.
```go-html-template
-{{ with $img.Exif }}
-Date: {{ .Date }}
-Lat/Long: {{ .Lat}}/{{ .Long }}
-Tags:
-{{ range $k, $v := .Tags }}
-TAG: {{ $k }}: {{ $v }}
-{{ end }}
+{{ with $image.Exif }}
+ Date: {{ .Date }}
+ Lat/Long: {{ .Lat }}/{{ .Long }}
+ Tags:
+ {{ range $k, $v := .Tags }}
+ TAG: {{ $k }}: {{ $v }}
+ {{ end }}
{{ end }}
```
-Or individually access EXIF data with dot access, e.g.:
+You may also access Exif fields individually, using the [`lang.FormatNumber`] function to format the fields as needed.
```go-html-template
-{{ with $src.Exif }}
+{{ with $image.Exif }}
<ul>
- {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
- {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.NumFmt 2 . }}</li>{{ end }}
- {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.NumFmt 2 . }}</li>{{ end }}
- {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
- {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
- {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
- {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
- {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
+ {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
+ {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
+ {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
+ {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
+ {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
+ {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
</ul>
{{ end }}
```
-Some fields may need to be formatted with [`lang.FormatNumberCustom`]({{< relref "functions/lang" >}}) function to prevent display like `Aperture: 2.278934289` instead of `Aperture: 2.28`.
-
-#### Exif fields
+#### Exif Variables
-Date
-: "photo taken" date/time
+.Date
+: Image creation date/time. Format with the [time.Format] function.
-Lat
-: "photo taken where", GPS latitude
+.Lat
+: GPS latitude in degrees.
-Long
-: "photo taken where", GPS longitude
+.Long
+: GPS longitude in degrees.
-See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif.
+.Tags
+: A collection of the available Exif tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
## Image Processing Options
-In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options.
+The `Resize`, `Fit`, `Fill`, and `Crop` methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
-### Background Color
-
-The background color to fill into the transparency layer. This is mostly useful when converting to a format that does not support transparency, e.g. `JPEG`.
+### Dimensions
-You can set the background color to use with a 3 or 6 digit hex code starting with `#`.
+With the `Resize` method you must specify width, height, or both. The `Fit`, `Fill`, and `Crop` methods require both width and height. All dimensions are in pixels.
-```go
-{{ $image.Resize "600x jpg #b31280" }}
+```go-html-template
+{{ $image := $image.Resize "600x" }}
+{{ $image := $image.Resize "x400" }}
+{{ $image := $image.Resize "600x400" }}
+{{ $image := $image.Fit "600x400" }}
+{{ $image := $image.Fill "600x400" }}
+{{ $image := $image.Crop "600x400" }}
```
-For color codes, see https://www.google.com/search?q=color+picker
+### Rotation
+
+Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%:
-**Note** that you also set a default background color to use, see [Image Processing Config](#image-processing-config).
+```go-html-template
+{{ $image = $image.Resize "200x r90" }}
+```
-### JPEG and WebP Quality
+In the example above, the width represents the desired width _after_ rotation.
-Only relevant for JPEG and WebP images, values 1 to 100 inclusive, higher is better. Default is 75.
+To rotate an image without scaling, use the dimensions of the original image:
-```go
-{{ $image.Resize "600x q50" }}
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
```
-{{< new-in "0.83.0" >}} WebP support was added in Hugo 0.83.0.
+In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation.
-### Hint
+### Anchor
- {{< new-in "0.83.0" >}}
+When using the `Crop` or `Fill` method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
- {{< new-in "0.83.0" >}}
+The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration](#processing-options).
-Hint about what type of image this is. Currently only used when encoding to WebP.
+For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:
-Default value is `photo`.
+```go-html-template
+{{ $image.Crop "200x100 TopLeft" }}
+```
+
+If you apply rotation when using the `Crop` or `Fill` method, specify the anchor relative to the rotated image.
+
+### Target Format
+
+By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`.
+
+```go-html-template
+{{ $image.Resize "600x webp" }}
+```
-Valid values are `picture`, `photo`, `drawing`, `icon`, or `text`.
+To convert an image without scaling, use the dimensions of the original image:
-```go
-{{ $image.Resize "600x webp drawing" }}
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
```
-### Rotate
+### Quality
+
+Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.
-Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images.
+The default value is 75. You may override the default value in the [site configuration](#processing-options).
-```go
-{{ $image.Resize "600x r90" }}
+```go-html-template
+{{ $image.Resize "600x webp q50" }}
```
-### Anchor
+### Hint
+
+<!-- Specifies a libwebp preset, not a libwebp image hint. -->
-Only relevant for the `Crop` and `Fill` methods. This is useful for thumbnail generation where the main motive is located in, say, the left corner.
+Applicable to WebP images, this option corresponds to a set of pre-defined encoding parameters.
-Valid values are `Smart`, `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`.
+Value|Example
+:--|:--
+`drawing`|Hand or line drawing with high-contrast details
+`icon`|Small colorful image
+`photo`|Outdoor photograph with natural lighting
+`picture`|Indoor photograph such as a portrait
+`text`|Image that is primarily text
-Default value is `Smart`, which uses [Smartcrop](https://github.com/muesli/smartcrop) to determine the best crop.
+The default value is `photo`. You may override the default value in the [site configuration](#processing-options).
-```go
-{{ $image.Fill "300x200 BottomLeft" }}
+```go-html-template
+{{ $image.Resize "600x webp picture" }}
```
-### Resample Filter
+### Background Color
-Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling.
+When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image.
-Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`.
+Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
-See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test.
+The default value is `#ffffff` (white). You may override the default value in the [site configuration](#processing-options).
-```go
-{{ $image.Resize "600x400 Gaussian" }}
+```go-html-template
+{{ $image.Resize "600x jpg #b31280" }}
```
-### Target Format
+### Resampling Filter
+
+You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
-By default the images is encoded in the source format, but you can set the target format as an option.
+Filter|Description
+:--|:--
+`Box`|Simple and fast averaging filter appropriate for downscaling
+`Lanczos`|High-quality resampling filter for photographic images yielding sharp results
+`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+`NearestNeighbor`|Fastest resampling filter, no antialiasing
-Valid values are `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, and `webp`.
+The default value is `Box`. You may override the default value in the [site configuration](#processing-options).
-```go
-{{ $image.Resize "600x jpg" }}
+```go-html-template
+{{ $image.Resize "600x400 Lanczos" }}
```
-{{< new-in "0.83.0" >}} WebP support was added in Hugo 0.83.0.
+See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
## Image Processing Examples
@@ -261,79 +357,83 @@ _The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pe
{{< imgproc sunset Resize "300x q10" />}}
-This is the shortcode used in the examples above:
+This is the shortcode used to generate the examples above:
{{< code file="layouts/shortcodes/imgproc.html" >}}
{{< readfile file="layouts/shortcodes/imgproc.html" >}}
{{< /code >}}
-And it is used like this:
+Call the shortcode from your markdown like this:
```go-html-template
{{</* imgproc sunset Resize "300x" /*/>}}
```
{{% note %}}
-**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**.
+Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**.
{{% /note %}}
-## Image Processing Config
+## Imaging Configuration
-You can configure an `imaging` section in `config.toml` with default image processing options:
+### Processing Options
-```toml
-[imaging]
-# Default resample filter used for resizing. Default is Box,
-# a simple and fast averaging filter appropriate for downscaling.
-# See https://github.com/disintegration/imaging
-resampleFilter = "box"
+Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
-# Default JPEG or WebP quality setting. Default is 75.
+{{< code-toggle file="config" copy=true >}}
+[imaging]
+resampleFilter = "Box"
quality = 75
-
-# Default hint about what type of image. Currently only used for WebP encoding.
-# Default is "photo".
-# Valid values are "picture", "photo", "drawing", "icon", or "text".
hint = "photo"
-
-# Anchor used when cropping pictures with either .Fill or .Crop
-# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop
-# Smart Cropping is content aware and tries to find the best crop for each image.
-# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
-anchor = "smart"
-
-# Default background color.
-# Hugo will preserve transparency for target formats that supports it,
-# but will fall back to this color for JPEG.
-# Expects a standard HEX color string with 3 or 6 digits.
-# See https://www.google.com/search?q=color+picker
+anchor = "Smart"
bgColor = "#ffffff"
+{{< /code-toggle >}}
+
+anchor
+: See image processing options: [anchor](#anchor).
+
+bgColor
+: See image processing options: [background color](#background-color).
+
+hint
+: See image processing options: [hint](#hint).
+
+quality
+: See image processing options: [quality](#quality).
+resampleFilter
+: See image processing options: [resampling filter](#resampling-filter).
+