diff options
Diffstat (limited to 'docs/content')
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). + +### Exif Data + +Define an `imaging.exif` section in your site configuration to control the availability of Exif data. + +{{< c |