diff options
Diffstat (limited to 'docs/content/en/content-management/image-processing/index.md')
| -rw-r--r-- | docs/content/en/content-management/image-processing/index.md | 137 |
1 files changed, 32 insertions, 105 deletions
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md index 50e4b1e72..8d60c4f93 100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@ -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)_ - -{{< imgproc "sunset.jpg" "resize 300x" />}} - -{{< imgproc "sunset.jpg" "fill 90x120 left" />}} - -{{< imgproc "sunset.jpg" "fill 90x120 right" />}} - -{{< imgproc "sunset.jpg" "fit 90x90" />}} - -{{< imgproc "sunset.jpg" "crop 250x250 center" />}} - -{{< imgproc "sunset.jpg" "resize 300x q10" />}} - -This is the shortcode used to generate the examples above: - -{{< 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 +_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)_ -Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options). +{{< imgproc path="sunset.jpg" spec="resize 480x" alt="A sunset" />}} -{{< code-toggle config=imaging />}} +{{< imgproc path="sunset.jpg" spec="fill 120x150 left" alt="A sunset" />}} -anchor -: See image processing options: [anchor](#anchor). +{{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}} -bgColor -: See image processing options: [background color](#background-color). +{{< imgproc path="sunset.jpg" spec="fit 120x120" alt="A sunset" />}} -hint -: See image processing options: [hint](#hint). +{{< imgproc path="sunset.jpg" spec="crop 240x240 center" alt="A sunset" />}} -quality -: See image processing options: [quality](#quality). +{{< imgproc path="sunset.jpg" spec="resize 360x q10" alt="A sunset" />}} -resampleFilter -: See image processing options: [resampling filter](#resampling-filter). +## Configuration -### 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 `""`. - -includeFields -: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`. - -{{% 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 |