diff options
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. -### Hint +### Anchor - {{< new-in "0.83.0" >}} +When using the `Crop` or `Fill` method, the _anchor_ determines the placement of the |