mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-17 21:01:26 +02:00
Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'
This commit is contained in:
Bjørn Erik Pedersen
@@ -5,18 +5,174 @@ categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: '[]string'
|
||||
returnType: '[]images.Color'
|
||||
signatures: [RESOURCE.Colors]
|
||||
toc: true
|
||||
math: true
|
||||
---
|
||||
|
||||
{{< new-in 0.104.0 >}}
|
||||
|
||||
The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
|
||||
|
||||
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
|
||||
|
||||
## Methods
|
||||
|
||||
Each color is an object with the following methods:
|
||||
|
||||
ColorHex
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.
|
||||
|
||||
Luminance
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
|
||||
|
||||
{{% note %}}
|
||||
Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments.
|
||||
|
||||
Hugo renders an `images.Color` object as a hexadecimal color value.
|
||||
|
||||
[`images.Dither`]: /functions/images/dither/
|
||||
[`images.Padding`]: /functions/images/padding/
|
||||
[`images.Text`]: /functions/images/text/
|
||||
{{% /note %}}
|
||||
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
|
||||
|
||||
## Sorting
|
||||
|
||||
As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974]
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Color</th>
|
||||
<th>Relative luminance</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range .Colors }}
|
||||
<tr>
|
||||
<td>{{ .ColorHex }}</td>
|
||||
<td>{{ .Luminance | lang.FormatNumber 4 }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled image.
|
||||
Hugo renders this to:
|
||||
|
||||
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
|
||||
ColorHex|Relative luminance
|
||||
:--|:--
|
||||
`#bebebd`|`0.5145`
|
||||
`#514947`|`0.0697`
|
||||
`#768a9a`|`0.2436`
|
||||
`#647789`|`0.1771`
|
||||
`#90725e`|`0.1877`
|
||||
`#a48974`|`0.2704`
|
||||
|
||||
To sort by dominance with the least dominant color first:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Colors | collections.Reverse }}
|
||||
```
|
||||
|
||||
To sort by relative luminance with the darkest color first:
|
||||
|
||||
```go-html-template
|
||||
{{ range sort .Colors "Luminance" }}
|
||||
```
|
||||
|
||||
To sort by relative luminance with the lightest color first, use either of these constructs:
|
||||
|
||||
```go-html-template
|
||||
{{ range sort .Colors "Luminance" | collections.Reverse }}
|
||||
{{ range sort .Colors "Luminance" "desc" }}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Image borders
|
||||
|
||||
To add a 5 pixel border to an image using the most dominant color:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $mostDominant := index .Colors 0 }}
|
||||
{{ $filter := images.Padding 5 $mostDominant }}
|
||||
{{ with .Filter $filter }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
To add a 5 pixel border to an image using the darkest dominant color:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $darkest := index (sort .Colors "Luminance") 0 }}
|
||||
{{ $filter := images.Padding 5 $darkest }}
|
||||
{{ with .Filter $filter }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Light text on dark background
|
||||
|
||||
To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $darkest := index (sort .Colors "Luminance") 0 }}
|
||||
{{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
|
||||
<div style="background: {{ $darkest }};">
|
||||
<div style="color: {{ $lightest }};">
|
||||
<p>This is light text on a dark background.</p>
|
||||
</div>
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### WCAG contrast ratio
|
||||
|
||||
In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
|
||||
|
||||
The WCAG defines the [contrast ratio] as:
|
||||
|
||||
$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
|
||||
|
||||
where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
|
||||
|
||||
Calculate the contrast ratio to determine WCAG conformance:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
|
||||
{{ $darkest := index (sort .Colors "Luminance") 0 }}
|
||||
{{ $cr := div
|
||||
(add $lightest.Luminance 0.05)
|
||||
(add $darkest.Luminance 0.05)
|
||||
}}
|
||||
{{ if ge $cr 7.5 }}
|
||||
{{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
|
||||
{{ else if ge $cr 4.5 }}
|
||||
{{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
|
||||
{{ else }}
|
||||
{{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
|
||||
[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
|
||||
[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
|
||||
[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
|
||||
[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
|
||||
|
||||
@@ -12,7 +12,7 @@ toc:
|
||||
|
||||
The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`.
|
||||
|
||||
[resource type]: /methods/resource/resourcetype
|
||||
[resource type]: /methods/resource/resourcetype/
|
||||
|
||||
{{< code file=assets/quotations/kipling.txt >}}
|
||||
He travels the fastest who travels alone.
|
||||
|
||||
@@ -13,7 +13,7 @@ action:
|
||||
|
||||
The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
|
||||
|
||||
[`resources.GetRemote`]: functions/resources/getremote
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
@@ -50,4 +50,4 @@ TransferEncoding
|
||||
: (`string`) The transfer encoding.
|
||||
|
||||
|
||||
[`resources.GetRemote`]: functions/resources/getremote
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
|
||||
@@ -13,7 +13,7 @@ action:
|
||||
|
||||
The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
|
||||
|
||||
[`resources.GetRemote`]: functions/resources/getremote
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
|
||||
In this example we send an HTTP request to a nonexistent domain:
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Applicable to JPEG and TIFF images, the `Exif` method on an image `Resource` obj
|
||||
## Methods
|
||||
|
||||
Date
|
||||
: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
|
||||
: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
|
||||
|
||||
Lat
|
||||
: (`float64`) Returns the GPS latitude in degrees.
|
||||
@@ -75,4 +75,4 @@ To list specific values:
|
||||
|
||||
[exif]: https://en.wikipedia.org/wiki/Exif
|
||||
[site configuration]: /content-management/image-processing/#exif-data
|
||||
[`time.Format`]: /functions/time/format
|
||||
[`time.Format`]: /functions/time/format/
|
||||
|
||||
@@ -39,7 +39,7 @@ To apply two or more filters, executing from left to right:
|
||||
|
||||
You can also apply image filters using the [`images.Filter`] function.
|
||||
|
||||
[`images.Filter`]: /functions/images/filter
|
||||
[`images.Filter`]: /functions/images/filter/
|
||||
|
||||
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Key
|
||||
description: Returns the unique key for the given resource, equivalent to its publishing path.
|
||||
draft: true
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -40,6 +41,6 @@ The `Key` method is useful if you need to get the resource's publishing path wit
|
||||
|
||||
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
|
||||
|
||||
[`Permalink`]: /methods/resource/permalink
|
||||
[`RelPermalink`]: /methods/resource/relpermalink
|
||||
[`resources.Copy`]: /functions/resources/copy
|
||||
[`Permalink`]: /methods/resource/permalink/
|
||||
[`RelPermalink`]: /methods/resource/relpermalink/
|
||||
[`resources.Copy`]: /functions/resources/copy/
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Name
|
||||
description: Returns the name of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type.
|
||||
description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -20,51 +20,63 @@ With a [global resource], the `Name` method returns the path to the resource, re
|
||||
```text
|
||||
assets/
|
||||
└── images/
|
||||
└── a.jpg
|
||||
└── Sunrise in Bryce Canyon.jpg
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ .Name }} → images/a.jpg
|
||||
{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
|
||||
{{ .Name }} → /images/Sunrise in Bryce Canyon.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Page resource
|
||||
|
||||
With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle.
|
||||
With a [page resource], if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── post-1/
|
||||
│ │ ├── images/
|
||||
│ │ │ └── a.jpg
|
||||
│ │ └── index.md
|
||||
│ └── _index.md
|
||||
├── example/
|
||||
│ ├── images/
|
||||
│ │ └── a.jpg
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
{{< code-toggle file=content/example/index.md fm=true >}}
|
||||
title = 'Example'
|
||||
[[resources]]
|
||||
src = 'images/a.jpg'
|
||||
name = 'Sunrise in Bryce Canyon'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "images/a.jpg" }}
|
||||
{{ .Name }} → Sunrise in Bryce Canyon
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
You can also capture the image by specifying its `name` instead of its path:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "Sunrise in Bryce Canyon" }}
|
||||
{{ .Name }} → Sunrise in Bryce Canyon
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
If you do not create an element in the `resources` array in front matter, the `Name` method returns the file path, relative to the page bundle.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── example/
|
||||
│ ├── images/
|
||||
│ │ └── Sunrise in Bryce Canyon.jpg
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "images/a.jpg" }}
|
||||
{{ .Name }} → images/a.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter:
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'Post 1'
|
||||
[[resources]]
|
||||
src = 'images/a.jpg'
|
||||
name = 'cat'
|
||||
title = 'Felix the cat'
|
||||
[resources.params]
|
||||
temperament = 'malicious'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "cat" }}
|
||||
{{ .Name }} → cat
|
||||
{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
|
||||
{{ .Name }} → images/Sunrise in Bryce Canyon.jpg
|
||||
{{ end }}
|
||||
```
|
||||
## Remote resource
|
||||
@@ -73,10 +85,11 @@ With a [remote resource], the `Name` method returns a hashed file name.
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
|
||||
{{ .Name }} → a_18432433023265451104.jpg
|
||||
{{ .Name }} → /a_18432433023265451104.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[global resource]: /getting-started/glossary/#global-resource
|
||||
[logical path]: /getting-started/glossary/#logical-path
|
||||
[page resource]: /getting-started/glossary/#page-resource
|
||||
[remote resource]: /getting-started/glossary/#remote-resource
|
||||
|
||||
@@ -62,4 +62,4 @@ Hugo renders:
|
||||
|
||||
See the [page resources] section for more information.
|
||||
|
||||
[page resources]: /content-management/page-resources
|
||||
[page resources]: /content-management/page-resources/
|
||||
|
||||
@@ -7,7 +7,6 @@ action:
|
||||
related:
|
||||
- methods/resource/RelPermalink
|
||||
- methods/resource/Publish
|
||||
- methods/resource/Key
|
||||
returnType: string
|
||||
signatures: [RESOURCE.Permalink]
|
||||
---
|
||||
|
||||
@@ -59,8 +59,8 @@ The `Process` method is also available as a filter, which is more effective if y
|
||||
example=true
|
||||
>}}
|
||||
|
||||
[`Crop`]: /methods/resource/crop
|
||||
[`Fill`]: /methods/resource/fill
|
||||
[`Fit`]: /methods/resource/fit
|
||||
[`Resize`]: /methods/resource/resize
|
||||
[`images.Process`]: /functions/images/process
|
||||
[`Crop`]: /methods/resource/crop/
|
||||
[`Fill`]: /methods/resource/fill/
|
||||
[`Fit`]: /methods/resource/fit/
|
||||
[`Resize`]: /methods/resource/resize/
|
||||
[`images.Process`]: /functions/images/process/
|
||||
|
||||
@@ -7,7 +7,6 @@ action:
|
||||
related:
|
||||
- methods/resource/Permalink
|
||||
- methods/resource/RelPermalink
|
||||
- methods/resource/Key
|
||||
returnType: nil
|
||||
signatures: [RESOURCE.Publish]
|
||||
---
|
||||
|
||||
@@ -7,7 +7,6 @@ action:
|
||||
related:
|
||||
- methods/resource/Permalink
|
||||
- methods/resource/Publish
|
||||
- methods/resource/Key
|
||||
returnType: string
|
||||
signatures: [RESOURCE.RelPermalink]
|
||||
---
|
||||
|
||||
@@ -20,73 +20,65 @@ With a [global resource], the `Title` method returns the path to the resource, r
|
||||
```text
|
||||
assets/
|
||||
└── images/
|
||||
└── a.jpg
|
||||
└── Sunrise in Bryce Canyon.jpg
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ .Title }} → images/a.jpg
|
||||
{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
|
||||
{{ .Title }} → /images/Sunrise in Bryce Canyon.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Page resource
|
||||
|
||||
With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle.
|
||||
With a [page resource], if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── post-1/
|
||||
│ │ ├── images/
|
||||
│ │ │ └── a.jpg
|
||||
│ │ └── index.md
|
||||
│ └── _index.md
|
||||
├── example/
|
||||
│ ├── images/
|
||||
│ │ └── a.jpg
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "images/a.jpg" }}
|
||||
{{ .Title }} → images/a.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
If you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter:
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'Post 1'
|
||||
{{< code-toggle file=content/example/index.md fm=true >}}
|
||||
title = 'Example'
|
||||
[[resources]]
|
||||
src = 'images/a.jpg'
|
||||
name = 'cat'
|
||||
title = 'Felix the cat'
|
||||
[resources.params]
|
||||
temperament = 'malicious'
|
||||
title = 'A beautiful sunrise in Bryce Canyon'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "cat" }}
|
||||
{{ .Title }} → Felix the cat
|
||||
{{ with .Resources.Get "images/a.jpg" }}
|
||||
{{ .Title }} → A beautiful sunrise in Bryce Canyon
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter.
|
||||
If you do not create an element in the `resources` array in front matter, the `Title` method returns the file path, relative to the page bundle.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── lessons/
|
||||
│ ├── lesson-1/
|
||||
│ │ ├── _objectives.md <-- resource type = page
|
||||
│ │ └── index.md
|
||||
│ └── _index.md
|
||||
├── example/
|
||||
│ ├── images/
|
||||
│ │ └── Sunrise in Bryce Canyon.jpg
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ with .Resources.Get "Sunrise in Bryce Canyon.jpg" }}
|
||||
{{ .Title }} → images/Sunrise in Bryce Canyon.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Remote resource
|
||||
|
||||
With a [remote resource], the `Title` method returns a hashed file name.
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
|
||||
{{ .Title }} → a_18432433023265451104.jpg
|
||||
{{ .Title }} → /a_18432433023265451104.jpg
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
Reference in New Issue
Block a user