From: Bjørn Erik Pedersen Date: Sun, 29 Oct 2023 10:33:05 +0000 (+0100) Subject: Merge commit 'aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=0baa4f983;p=brevno-suite%2Fhugo Merge commit 'aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a' --- 0baa4f9837d58c8dfa7157fa264438df5af71fbe diff --cc docs/content/en/functions/collections/Apply.md index d7401908a,000000000..4d972b853 mode 100644,000000..100644 --- a/docs/content/en/functions/collections/Apply.md +++ b/docs/content/en/functions/collections/Apply.md @@@ -1,115 -1,0 +1,37 @@@ +--- +title: collections.Apply +linkTitle: apply - description: Given an array or slice, `apply` returns a new slice with a function applied over it. ++description: Returns a new collection with each element transformed by the given function. +categories: [functions] +keywords: [] +menu: + docs: + parent: functions +function: + aliases: [apply] - returnType: any - signatures: ['collections.Apply COLLECTION FUNCTION [PARAM...]'] ++ returnType: '[]any' ++ signatures: [collections.Apply COLLECTION FUNCTION PARAM...] +relatedFunctions: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice +aliases: [/functions/apply] +--- + - `apply` expects at least three arguments, depending on the function being applied. ++The `apply` function takes three or more arguments, depending on the function being applied to the collection elements. + - 1. The first argument is the sequence to operate on. - 2. The second argument is the name of the function as a string, which must be the name of a valid [template function]. - 3. After that, the arguments to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against. ++The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element. + - Here is an example of a content file with `names:` as a front matter field: - - {{< code-toggle file="content/example.md" fm=true copy=false >}} - title: Example - names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ] - {{< /code-toggle >}} - - You can then use `apply` as follows: + +```go-html-template - {{ apply .Params.names "urlize" "." }} - ``` ++{{ $s := slice "hello" "world" }} + - Which will result in the following: ++{{ $s = apply $s "strings.FirstUpper" "." }} ++{{ $s }} → [Hello World] + ++{{ $s = apply $s "strings.Replace" "." "l" "_" }} ++{{ $s }} → [He__o Wor_d] +``` - "derek-perkins", "joe-bergevin", "tanner-linsley" - ``` - - This is *roughly* equivalent to using the following with [`range`]: - - ```go-html-template - {{ range .Params.names }}{{ . | urlize }}{{ end }} - ``` - - However, it is not possible to provide the output of a range to the [`delimit`]function, so you need to `apply` it. - - If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *could* use the following snippets, respectively: - - {{< code file="layouts/partials/post-tag-list.html" copy=false >}} - {{ with .Params.tags }} -
- Tags: - {{ $len := len . }} - {{ if eq $len 1 }} - {{ partial "post-tag-link.html" (index . 0) }} - {{ else }} - {{ $last := sub $len 1 }} - {{ range first $last . }} - {{ partial "post-tag-link.html" . }}, - {{ end }} - {{ partial "post-tag-link.html" (index . $last) }} - {{ end }} -
- {{ end }} - {{< /code >}} - - {{< code file="layouts/partials/post-tag-link.html" copy=false >}} - {{ . }} - {{< /code >}} - - This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser. - - This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading. The combined and DRYer version is shown next: - - ```go-html-template - {{ with .Params.tags }} -
- Tags: - {{ $sort := sort . }} - {{ $links := apply $sort "partial" "post-tag-link.html" "." }} - {{ $clean := apply $links "chomp" "." }} - {{ delimit $clean ", " }} -
- {{ end }} - ``` - - Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [`chomp`] stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example: - - {{< code file="layouts/partials/post-tag-list.html" >}} - {{ with .Params.tags }} -
- Tags: - {{ delimit (apply (apply (sort .) "partial" "post-tag-link.html" ".") "chomp" ".") ", " }} -
- {{ end }} - {{< /code >}} - - {{% note %}} - `apply` does not work when receiving the sequence as an argument through a pipeline. - {{% /note %}} - - [`chomp`]: /functions/strings/chomp/ - [`delimit`]: /functions/collections/delimit/ - [template function]: /functions/ - [`range`]: /functions/go-template/range/ diff --cc docs/content/en/functions/images/index.md index f886caa72,000000000..3b71652cf mode 100644,000000..100644 --- a/docs/content/en/functions/images/index.md +++ b/docs/content/en/functions/images/index.md @@@ -1,300 -1,0 +1,300 @@@ +--- +title: Image filters +description: The images namespace provides a list of filters and other image related functions. +categories: [functions] +keywords: [] +aliases: [/functions/imageconfig/] +menu: + docs: + parent: functions +keywords: [images] +toc: true +--- + +See [images.Filter](#filter) for how to apply these filters to an image. + +## Process + +{{< new-in "0.119.0" >}} + - {{% funcsig %}} ++{{< funcsig >}} +images.Process SRC SPEC - {{% /funcsig %}} ++{{< /funcsig >}} + +A general purpose image processing function. + +This filter has all the same options as the [Process](/content-management/image-processing/#process) method, but using it as a filter may be more effective if you need to apply multiple filters to an image: + +```go-html-template +{{ $filters := slice + images.Grayscale + (images.GaussianBlur 8) + (images.Process "resize 200x jpg q30") +}} +{{ $img = $img | images.Filter $filters }} +``` + +## Overlay + - {{% funcsig %}} ++{{< funcsig >}} +images.Overlay SRC X Y - {{% /funcsig %}} ++{{< /funcsig >}} + +Overlay creates a filter that overlays the source image at position x y, e.g: + + +```go-html-template +{{ $logoFilter := (images.Overlay $logo 50 50 ) }} +{{ $img := $img | images.Filter $logoFilter }} +``` + +A shorter version of the above, if you only need to apply the filter once: + +```go-html-template +{{ $img := $img.Filter (images.Overlay $logo 50 50 )}} +``` + +The above will overlay `$logo` in the upper left corner of `$img` (at position `x=50, y=50`). + +## Opacity + +{{< new-in "0.119.0" >}} + - {{% funcsig %}} ++{{< funcsig >}} +images.Opacity SRC OPACITY - {{% /funcsig %}} ++{{< /funcsig >}} + +Opacity creates a filter that changes the opacity of an image. +The OPACITY parameter must be in range (0, 1). + +```go-html-template +{{ $img := $img.Filter (images.Opacity 0.5 )}} +``` + +This filter is most useful for target formats that support transparency, e.g. PNG. If the source image is e.g. JPG, the most effective way would be to combine it with the [`Process`] filter: + +```go-html-template +{{ $png := $jpg.Filter + (images.Opacity 0.5) + (images.Process "png") +}} +``` + +## Text + +Using the `Text` filter, you can add text to an image. + - {{% funcsig %}} ++{{< funcsig >}} +images.Text TEXT MAP) - {{% /funcsig %}} ++{{< /funcsig >}} + +The following example will add the text `Hugo rocks!` to the image with the specified color, size and position. + +```go-html-template +{{ $img := resources.Get "/images/background.png" }} +{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict + "color" "#ffffff" + "size" 60 + "linespacing" 2 + "x" 10 + "y" 20 +))}} +``` + +You can load a custom font if needed. Load the font as a Hugo `Resource` and set it as an option: + +```go-html-template +{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} +{{ $img := resources.Get "/images/background.png" }} +{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict + "font" $font +))}} +``` + +## Padding + +Padding creates a filter that resizes the image canvas without resizing the image. The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image. + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box + +{{% funcsig %}} +images.Padding V1 [V2] [V3] [V4] [COLOR] +{{% /funcsig %}} + +This example resizes the image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity. + +```go-html-template +{{ $img := resources.Get "images/a.jpg" }} +{{ $filters := slice + (images.Process "resize 300x webp") + (images.Padding 20 50 "#0705") +}} +{{ $img = $img.Filter $filters }} +``` + +To add a 2px gray border to an image: + +```go-html-template +{{ $img = $img.Filter (images.Padding 2 "#777") }} +``` + +## Brightness + - {{% funcsig %}} ++{{< funcsig >}} +images.Brightness PERCENTAGE - {{% /funcsig %}} ++{{< /funcsig >}} + +Brightness creates a filter that changes the brightness of an image. +The percentage parameter must be in range (-100, 100). + +### ColorBalance + - {{% funcsig %}} ++{{< funcsig >}} +images.ColorBalance PERCENTAGERED PERCENTAGEGREEN PERCENTAGEBLUE - {{% /funcsig %}} ++{{< /funcsig >}} + +ColorBalance creates a filter that changes the color balance of an image. +The percentage parameters for each color channel (red, green, blue) must be in range (-100, 500). + +## Colorize + - {{% funcsig %}} ++{{< funcsig >}} +images.Colorize HUE SATURATION PERCENTAGE - {{% /funcsig %}} ++{{< /funcsig >}} + +Colorize creates a filter that produces a colorized version of an image. +The hue parameter is the angle on the color wheel, typically in range (0, 360). +The saturation parameter must be in range (0, 100). +The percentage parameter specifies the strength of the effect, it must be in range (0, 100). + +## Contrast + - {{% funcsig %}} ++{{< funcsig >}} +images.Contrast PERCENTAGE - {{% /funcsig %}} ++{{< /funcsig >}} + +Contrast creates a filter that changes the contrast of an image. +The percentage parameter must be in range (-100, 100). + +## Gamma + - {{% funcsig %}} ++{{< funcsig >}} +images.Gamma GAMMA - {{% /funcsig %}} ++{{< /funcsig >}} + +Gamma creates a filter that performs a gamma correction on an image. +The gamma parameter must be positive. Gamma = 1 gives the original image. +Gamma less than 1 darkens the image and gamma greater than 1 lightens it. + +## GaussianBlur + - {{% funcsig %}} ++{{< funcsig >}} +images.GaussianBlur SIGMA - {{% /funcsig %}} ++{{< /funcsig >}} + +GaussianBlur creates a filter that applies a gaussian blur to an image. + +## Grayscale + - {{% funcsig %}} ++{{< funcsig >}} +images.Grayscale - {{% /funcsig %}} ++{{< /funcsig >}} + +Grayscale creates a filter that produces a grayscale version of an image. + +## Hue + - {{% funcsig %}} ++{{< funcsig >}} +images.Hue SHIFT - {{% /funcsig %}} ++{{< /funcsig >}} + +Hue creates a filter that rotates the hue of an image. +The hue angle shift is typically in range -180 to 180. + +## Invert + - {{% funcsig %}} ++{{< funcsig >}} +images.Invert - {{% /funcsig %}} ++{{< /funcsig >}} + +Invert creates a filter that negates the colors of an image. + +## Pixelate + - {{% funcsig %}} ++{{< funcsig >}} +images.Pixelate SIZE - {{% /funcsig %}} ++{{< /funcsig >}} + +Pixelate creates a filter that applies a pixelation effect to an image. + +## Saturation + - {{% funcsig %}} ++{{< funcsig >}} +images.Saturation PERCENTAGE - {{% /funcsig %}} ++{{< /funcsig >}} + +Saturation creates a filter that changes the saturation of an image. + +## Sepia + - {{% funcsig %}} ++{{< funcsig >}} +images.Sepia PERCENTAGE - {{% /funcsig %}} ++{{< /funcsig >}} + +Sepia creates a filter that produces a sepia-toned version of an image. + +## Sigmoid + - {{% funcsig %}} ++{{< funcsig >}} +images.Sigmoid MIDPOINT FACTOR - {{% /funcsig %}} ++{{< /funcsig >}} + +Sigmoid creates a filter that changes the contrast of an image using a sigmoidal function and returns the adjusted image. +It's a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail. + +## UnsharpMask + - {{% funcsig %}} ++{{< funcsig >}} +images.UnsharpMask SIGMA AMOUNT THRESHOLD - {{% /funcsig %}} ++{{< /funcsig >}} + +UnsharpMask creates a filter that sharpens an image. +The sigma parameter is used in a gaussian function and affects the radius of effect. +Sigma must be positive. Sharpen radius roughly equals 3 * sigma. +The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5. +The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05. + +## Other Functions + +### Filter + - {{% funcsig %}} ++{{< funcsig >}} +IMAGE | images.Filter FILTERS... - {{% /funcsig %}} ++{{< /funcsig >}} + +Can be used to apply a set of filters to an image: + +```go-html-template +{{ $img := $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Also see the [Filter Method](/content-management/image-processing/#filter). + +### ImageConfig + +Parses the image and returns the height, width, and color model. + +The `imageConfig` function takes a single parameter, a file path (_string_) relative to the _project's root directory_, with or without a leading slash. + - {{% funcsig %}} ++{{< funcsig >}} +images.ImageConfig PATH - {{% /funcsig %}} ++{{< /funcsig >}} + +```go-html-template +{{ with (imageConfig "favicon.ico") }} +favicon.ico: {{ .Width }} x {{ .Height }} +{{ end }} +``` + +[`Process`]: #process diff --cc docs/layouts/partials/docs/functions-signatures.html index 07c9cb768,000000000..b349739e9 mode 100644,000000..100644 --- a/docs/layouts/partials/docs/functions-signatures.html +++ b/docs/layouts/partials/docs/functions-signatures.html @@@ -1,12 -1,0 +1,12 @@@ +{{- with .Params.function.signatures }} +

Syntax

+ {{- range . }} + {{- $signature := . }} + {{- if $.Params.function.returnType }} + {{- $signature = printf "%s ⟼ %s" . $.Params.function.returnType }} + {{- end }} - 
++    
 +      {{- $signature -}}
 +    

 +  {{- end }}
 +{{- end -}}
diff --cc docs/layouts/shortcodes/funcsig.html
index 1709c60b0,000000000..77b0990a5
mode 100644,000000..100644
--- a/docs/layouts/shortcodes/funcsig.html
+++ b/docs/layouts/shortcodes/funcsig.html
@@@ -1,4 -1,0 +1,4 @@@
 +
Syntax

- 
++
 +    {{- .Inner -}}
- 

++