mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-23 21:53:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
docs/content/en/content-management/image-processing/index.md
View File

@@ -1,14 +1,8 @@
---
title: Image processing
description: Resize, crop, rotate, filter, and convert images.
categories: [content management,fundamentals]
keywords: [resources,images]
menu:
docs:
parent: content-management
weight: 90
toc: true
weight: 90
categories: []
keywords: []
---
## Image resources
@@ -17,7 +11,7 @@ To process an image you must access the file as a page resource, global resource
### Page resource
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.
{{% glossary-term "page resource" %}}
```text
content/
@@ -35,7 +29,7 @@ To access an image as a page resource:
### Global resource
A global resource is a file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
{{% glossary-term "global resource" %}}
```text
assets/
@@ -51,7 +45,9 @@ To access an image as a global resource:
### Remote resource
A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:
{{% glossary-term "remote resource" %}}
To access an image as a remote resource:
```go-html-template
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
@@ -104,17 +100,15 @@ Example 4: Skips rendering if there's problem accessing a remote resource.
The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
{{% note %}}
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, PNG, TIFF, and WebP images.
{{% /note %}}
> [!note]
> 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, PNG, TIFF, and WebP images.
### Process
{{< new-in 0.119.0 />}}
{{% note %}}
The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
{{% /note %}}
> [!note]
> The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
@@ -252,8 +246,6 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
Date
: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
[time.Format]: /functions/time/format/
Lat
: (`float64`) Returns the GPS latitude in degrees.
@@ -348,8 +340,6 @@ The default value is 75. You may override the default value in the [site configu
Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
Value|Example
:--|:--
`drawing`|Hand or line drawing with high-contrast details
@@ -399,86 +389,23 @@ See [github.com/disintegration/imaging] for the complete list of resampling filt
## Image processing examples
_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://bep.is) (Creative Commons Attribution-Share Alike 4.0 International license)_
{{< imgproc "sunset.jpg" "resize 300x" />}}
{{< imgproc path="sunset.jpg" spec="resize 480x" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "fill 90x120 left" />}}
{{< imgproc path="sunset.jpg" spec="fill 120x150 left" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "fill 90x120 right" />}}
{{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "fit 90x90" />}}
{{< imgproc path="sunset.jpg" spec="fit 120x120" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "crop 250x250 center" />}}
{{< imgproc path="sunset.jpg" spec="crop 240x240 center" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "resize 300x q10" />}}
{{< imgproc path="sunset.jpg" spec="resize 360x q10" alt="A sunset" />}}
This is the shortcode used to generate the examples above:
## Configuration
{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}}
Call the shortcode from your Markdown like this:
```go-html-template
{{</* imgproc "sunset.jpg" "resize 300x" /*/>}}
```
{{% note %}}
Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**.
{{% /note %}}
## Imaging configuration
### Processing options
Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
{{< code-toggle config=imaging />}}
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).
### EXIF data
Define an `imaging.exif` section in your site configuration to control the availability of EXIF data.
{{< code-toggle file=hugo >}}
[imaging.exif]
includeFields = ""
excludeFields = ""
disableDate = false
disableLatLong = false
{{< /code-toggle >}}
disableDate
: Hugo extracts the image creation date/time into `.Date`. Set this to `true` to disable. Default is `false`.
disableLatLong
: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`.
excludeFields
: Regular expression matching the EXIF tags to exclude from the `.Tags` collection. Default is&nbsp;`""`.
includeFields
: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is&nbsp;`""`. To include all available tags, set this value to&nbsp;`".*"`.
{{% note %}}
To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
{{% /note %}}
See [configure imaging](/configuration/imaging).
## Smart cropping of images
@@ -486,13 +413,13 @@ By default, Hugo uses the [Smartcrop] library when cropping images with the `Cro
Examples using the sunset image from above:
{{< imgproc "sunset.jpg" "fill 200x200 smart" />}}
{{< imgproc path="sunset.jpg" spec="fill 200x200 smart" alt="A sunset" />}}
{{< imgproc "sunset.jpg" "crop 200x200 smart" />}}
{{< imgproc path="sunset.jpg" spec="crop 200x200 smart" alt="A sunset" />}}
## Image processing performance consideration
Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a [CI/CD](g) workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with:
@@ -501,20 +428,20 @@ hugo --gc
```
[`anchor`]: /content-management/image-processing#anchor
[mounted]: /hugo-modules/configuration#module-configuration-mounts
[page bundle]: /content-management/page-bundles/
[`lang.FormatNumber`]: /functions/lang/formatnumber/
[filters]: /functions/images/filter/#image-filters
[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop
[Exif]: https://en.wikipedia.org/wiki/Exif
[`Process`]: #process
[`Colors`]: #colors
[`Crop`]: #crop
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
[`Exif`]: #exif
[`Fill`]: #fill
[`Filter`]: #filter
[`Fit`]: #fit
[`lang.FormatNumber`]: /functions/lang/formatnumber/
[`Process`]: #process
[`Resize`]: #resize
[site configuration]: #processing-options
[`time.Format`]: /functions/time/format/
[`with`]: /functions/go-template/with/
[EXIF]: https://en.wikipedia.org/wiki/Exif
[filters]: /functions/images/filter/#image-filters
[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
[site configuration]: /configuration/imaging/
[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop