Merge commit 'd276e901b36d2576ef8350ed96b17f66254eac1b'

28 files changed, 646 insertions, 372 deletions

diff --git a/docs/.cspell.json b/docs/.cspell.json
index 70811e515..2cac73c02 100644
--- a/docs/.cspell.json
+++ b/docs/.cspell.json
@@ -1,52 +1,89 @@
 {
   "version": "0.2",
   "words": [
+    "aaabaab",
     "aabb",
     "aabba",
     "aabbaa",
     "aabbaabb",
     "abourget",
+    "absurl",
     "adoc",
     "algolia",
+    "allowfullscreen",
+    "ananke",
     "anchorize",
     "anthonyfok",
     "asciidoctor",
     "attrlink",
+    "azblob",
+    "baseof",
+    "beevelop",
+    "bibtex",
     "Bjørn",
     "blackfriday",
     "blogue",
     "bogem",
+    "Bootcamp",
+    "brlink",
     "Brotli",
+    "Browsersync",
     "canonify",
+    "Catmull",
     "Catwoman",
     "Cheatsheet",
+    "choco",
     "chromastyles",
     "clockoon",
     "Cloudinary",
     "CNAME",
     "Codecademy's",
     "CODEOWNERS",
+    "Coen",
     "Commento",
     "Cond",
     "Contentful",
+    "copyrighthtml",
+    "corejs",
     "countrunes",
     "countwords",
     "crossreferences",
+    "datatable",
+    "DATOCMS",
+    "debugconfig",
+    "DELIM",
+    "dhersam",
     "digitalcraftsman",
     "Disqus",
+    "Dmdh",
+    "doas",
     "dokuwiki",
+    "dpkg",
     "DRING",
     "Emojify",
     "Enwrite",
+    "eopkg",
     "eparis",
     "errorf",
+    "erroridf",
+    "Evernote",
+    "exitwp",
+    "Feminella",
     "firstpost",
+    "Formspree",
+    "fpath",
     "Francia",
     "freenode",
+    "frontmatter",
     "funcs",
     "funcsig",
     "Garen",
+    "gcloud",
     "Getenv",
+    "getjson",
+    "getpage",
+    "Gmfc",
+    "Goel",
     "Gohugo",
     "gohugoio",
     "goldenbridge",
@@ -58,67 +95,142 @@
     "Grayscale",
     "Gruber",
     "gtag",
+    "hidecaption",
     "Hokus",
+    "hola",
+    "hügó",
+    "hugodeps",
     "hugodoc",
+    "Hugofy",
     "hugolang",
     "hugoversion",
+    "Hyas",
     "Hyvor",
     "iframes",
+    "ifttt",
+    "iife",
     "imgproc",
+    "importr",
+    "IMWQ",
     "indice",
+    "innershortcode",
     "Intelli",
     "interdoc",
     "IPTC",
+    "ismenucurrent",
     "Isset",
     "Isso",
+    "Jaco",
+    "johnpatitucci",
     "Joomla",
+    "JRBR",
     "jsonify",
     "katex",
+    "keycdn",
+    "KEYVALS",
     "kubernetes",
+    "Lanczos",
+    "langformatnumber",
     "lastmod",
+    "libwebp",
     "linktitle",
+    "Lipi",
+    "lrwxr",
+    "maingo",
     "markdownified",
     "markdownify",
     "mathjax",
+    "mdhender",
+    "mdshortcode",
     "mercredi",
     "Mittwoch",
+    "mkdir",
     "mmark",
     "monokai",
     "Morling",
+    "mspowerpoint",
+    "Multihost",
     "Muut",
+    "myclass",
+    "mydeployment",
+    "myindex",
+    "mylayout",
+    "mypage",
     "mypartials",
     "mypost",
+    "mysite",
+    "myspa",
+    "mystyle",
+    "mytheme",
+    "NDJSON",
     "needsexample",
+    "Netravali",
+    "newparam",
+    "Nikhil",
+    "Njjy",
+    "nlist",
     "nobr",
     "nocopy",
     "Norsk",
+    "nosniff",
+    "NOSQL",
+    "notoc",
     "novembre",
+    "NUMWORKERMULTIPLIER",
+    "Obhu",
+    "octohug",
     "Octopress",
+    "oldparam",
+    "onrender",
     "opengraph",
     "OWASP",
     "Pandoc",
+    "partialcached",
+    "Pastorius",
+    "Patitucci",
+    "PCRE",
     "peaceiris",
     "Pedersen",
+    "permalinkable",
     "plainify",
+    "POSIX",
+    "postprocess",
     "println",
     "publishdate",
     "Pygments",
     "querify",
+    "QVOMC",
+    "rdwatters",
     "readfile",
+    "rebinded",
     "REDIR",
     "reftext",
     "relatedfuncs",
     "relref",
+    "relurl",
     "remarkjs",
     "rgba",
     "rlimit",
+    "roboto",
+    "rssxml",
+    "rwxrwxrwx",
+    "safehtml",
     "safejs",
     "Samsa",
+    "Shekhar",
     "Shortcode",
     "Shortcodes",
     "Sindre",
+    "sitemapindex",
+    "sitemapxml",
     "Smartcrop",
+    "Sprintf",
+    "Startseite",
+    "strconv",
+    "stringifier",
     "struct",
+    "structs",
+    "subdir",
     "Talkyard",
     "taxo",
     "tbody",
@@ -126,20 +238,29 @@
     "testshortcodes",
     "thead",
     "Thinkful",
+    "TLDR",
     "TMPDIR",
     "tojson",
     "Torikian",
     "totoml",
     "toyaml",
+    "twitteruser",
+    "Unmarshal",
     "Unmarshal",
     "urlize",
+    "urlset",
     "vimrc",
     "wanghc",
     "Wappalyzer",
     "warnf",
     "webp",
+    "Wercker",
     "wibble",
+    "wordcount",
     "workson",
+    "xvzf",
+    "yoyoyo",
+    "Zgotmpl",
     "zzbbaabb"
   ],
   "language": "en,en-GB,en-US,de,fr",
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.