Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'

2025-08-20 21:31:32 +02:00 · 2023-10-20 09:43:56 +02:00
parent fd38171810 e509cac533
commit e2dd4cd05f
298 changed files with 4568 additions and 1991 deletions
--- a/docs/content/en/functions/collections/After.md
+++ b/docs/content/en/functions/collections/After.md
@@ -0,0 +1,66 @@
+---
+title: collections.After
+linkTitle: after
+description: Slices an array to the items after the Nth item.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [after]
+  returnType: any
+  signatures: [collections.After INDEX COLLECTION]
+relatedFunctions:
+  - collections.After
+  - collections.First
+  - collections.Last
+aliases: [/functions/after]
+---
+
+The following shows `after` being used in conjunction with the [`slice`]function:
+
+```go-html-template
+{{ $data := slice "one" "two" "three" "four" }}
+{{ range after 2 $data }}
+    {{ . }}
+{{ end }}
+→ ["three", "four"]
+```
+
+## Example of `after` with `first`: 2nd&ndash;4th most recent articles
+
+You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows:
+
+1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
+2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+
+{{< code file="layouts/section/articles.html" >}}
+{{ define "main" }}
+<section class="row featured-article">
+  <h2>Featured Article</h2>
+  {{ range first 1 .Pages.ByPublishDate.Reverse }}
+  <header>
+      <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
+  </header>
+  <p>{{ .Description }}</p>
+{{ end }}
+</section>
+<div class="row recent-articles">
+  <h2>Recent Articles</h2>
+  {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
+    <section class="recent-article">
+      <header>
+          <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
+      </header>
+      <p>{{ .Description }}</p>
+    </section>
+  {{ end }}
+</div>
+{{ end }}
+{{< /code >}}
+
+[`first`]: /functions/collections/first
+[list/section page]: /templates/section-templates
+[lists]: /templates/lists/#order-content
+[`slice`]: /functions/collections/slice/
--- a/docs/content/en/functions/collections/Append.md
+++ b/docs/content/en/functions/collections/Append.md
@@ -0,0 +1,107 @@
+---
+title: collections.Append
+linkTitle: append
+description: Appends one or more elements to a slice and returns the resulting slice.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [append]
+  returnType: any
+  signatures:
+    - COLLECTION | collections.Append ELEMENT [ELEMENT]...
+    - COLLECTION | collections.Append COLLECTION
+relatedFunctions:
+  - collections.Append
+  - collections.Merge
+  - collections.Slice
+aliases: [/functions/append]
+---
+
+This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below.
+
+Append a single element to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" }}
+{{ $s }} → [a b c]
+```
+
+Append two elements to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" "d" }}
+{{ $s }} → [a b c d]
+```
+
+Append two elements, as a slice, to a slice. This produces the same result as the previous example:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [a b c d]
+```
+
+Start with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append "a" }}
+{{ $s }} → [a]
+
+{{ $s = $s | append "b" "c" }}
+{{ $s }} → [a b c]
+
+{{ $s = $s | append (slice "d" "e") }}
+{{ $s }} → [a b c d e]
+```
+
+If you start with a slice of a slice:
+
+```go-html-template
+{{ $s := slice (slice "a" "b") }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+To create a slice of slices, starting with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append (slice (slice "a" "b")) }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append  (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+Although the elements in the examples above are strings, you can use the `append` function with any data type, including Pages. For example, on the home page of a corporate site, to display links to the two most recent press releases followed by links to the four most recent articles:
+
+```go-html-template
+{{ $p := where site.RegularPages "Type" "press-releases" | first 2 }}
+{{ $p = $p | append (where site.RegularPages "Type" "articles" | first 4) }}
+
+{{ with $p }}
+  <ul>
+    {{ range . }}
+      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+    {{ end }}
+  </ul>
+{{ end }}
+```
--- a/docs/content/en/functions/collections/Apply.md
+++ b/docs/content/en/functions/collections/Apply.md
@@ -0,0 +1,115 @@
+---
+title: collections.Apply
+linkTitle: apply
+description: Given an array or slice, `apply` returns a new slice with a function applied over it.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [apply]
+  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.
+
+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.
+
+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" "." }}
+```
+
+Which will result in the following:
+
+```
+"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 }}
+  <div class="tags-list">
+    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 }}
+  </div>
+{{ end }}
+{{< /code >}}
+
+{{< code file="layouts/partials/post-tag-link.html" copy=false >}}
+<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
+{{< /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 }}
+  <div class="tags-list">
+    Tags:
+    {{ $sort := sort . }}
+    {{ $links := apply $sort "partial" "post-tag-link.html" "." }}
+    {{ $clean := apply $links "chomp" "." }}
+    {{ delimit $clean ", " }}
+  </div>
+{{ 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 }}
+  <div class="tags-list">
+    Tags:
+    {{ delimit (apply (apply (sort .) "partial" "post-tag-link.html" ".") "chomp" ".") ", " }}
+  </div>
+{{ 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/
--- a/docs/content/en/functions/collections/Complement.md
+++ b/docs/content/en/functions/collections/Complement.md
@@ -0,0 +1,86 @@
+---
+title: collections.Complement
+linkTitle: complement
+description: Returns the elements of the last collection that are not in any of the others.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [complement]
+  returnType: any
+  signatures: ['collections.Complement COLLECTION [COLLECTION]...']
+relatedFunctions:
+  - collections.Complement
+  - collections.Intersect
+  - collections.SymDiff
+  - collections.Union
+aliases: [/functions/complement]
+---
+
+To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
+
+```go-html-template
+{{ $c1 := slice 3 }}
+{{ $c2 := slice 4 5 }}
+{{ $c3 := slice 1 2 3 4 5 }}
+
+{{ complement $c1 $c2 $c3 }} → [1 2]
+```
+
+{{% note %}}
+Make your code simpler to understand by using a [chained pipeline]:
+
+[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
+{{% /note %}}
+
+
+```go-html-template
+{{ $c3 | complement $c1 $c2 }} → [1 2]
+```
+
+You can also use the `complement` function with page collections. Let's say your site has five content types:
+
+```text
+content/
+├── blog/
+├── books/
+├── faqs/
+├── films/
+└── songs/
+```
+
+To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
+
+```go-html-template
+{{ $blog := where site.RegularPages "Type" "blog" }}
+{{ $faqs := where site.RegularPages "Type" "faqs" }}
+{{ range site.RegularPages | complement $blog $faqs }}
+  <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+{{% note %}}
+Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
+
+[`where`]: /functions/collections/where
+{{% /note %}} 
+
+```go-html-template
+{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
+  <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+In this example we use the `complement` function to remove [stop words] from a sentence:
+
+```go-html-template
+{{ $text := "The quick brown fox jumps over the lazy dog" }}
+{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
+{{ $filtered := split $text " " | complement $stopWords }}
+
+{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
+```
+
+[stop words]: https://en.wikipedia.org/wiki/Stop_word
--- a/docs/content/en/functions/collections/Delimit.md
+++ b/docs/content/en/functions/collections/Delimit.md
@@ -0,0 +1,43 @@
+---
+title: collections.Delimit
+linkTitle: delimit
+description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [delimit]
+  returnType: template.HTML
+  signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]']
+relatedFunctions:
+  - collections.Apply
+  - collections.Delimit
+  - collections.In
+  - collections.Reverse
+  - collections.Seq
+  - collections.Slice
+  - strings.Split
+aliases: [/functions/delimit]
+---
+
+Delimit a slice:
+
+```go-html-template
+{{ $s := slice "b" "a" "c" }}
+{{ delimit $s ", " }} → "b, a, c"
+{{ delimit $s ", " " and "}} → "b, a and c"
+```
+
+Delimit a map:
+
+{{% note %}}
+The `delimit` function sorts maps by key, returning the values.
+{{% /note %}}
+
+```go-html-template
+{{ $m := dict "b" 2 "a" 1 "c" 3 }}
+{{ delimit $m ", " }} → "1, 2, 3"
+{{ delimit $m ", " " and "}} → "1, 2 and 3"
+```
--- a/docs/content/en/functions/collections/Dictionary.md
+++ b/docs/content/en/functions/collections/Dictionary.md
@@ -0,0 +1,52 @@
+---
+title: collections.Dictionary
+linkTitle: dict
+description: Creates a map from a list of key and value pairs.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [dict]
+  returnType: mapany
+  signatures: ['collections.Dictionary KEY VALUE [KEY VALUE]...']
+relatedFunctions:
+  - collections.Dictionary
+  - collections.Group
+  - collections.Index
+  - collections.IsSet
+  - collections.Where
+aliases: [/functions/dict]
+---
+
+`dict` is especially useful for passing more than one value to a partial template.
+
+Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
+
+```go-text-template
+{{ $m := dict (slice "a" "b" "c") "value" }}
+```
+
+## Example: using `dict` to pass multiple values to a `partial`
+
+The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
+
+### Partial definition
+
+{{< code file="layouts/partials/svgs/external-links.svg" >}}
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
+<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
+</svg>
+{{< /code >}}
+
+### Partial call
+
+The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
+
+{{< code file="layouts/_default/list.html" >}}
+{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
+{{< /code >}}
+
+[partials]: /templates/partials/
--- a/docs/content/en/functions/collections/EchoParam.md
+++ b/docs/content/en/functions/collections/EchoParam.md
@@ -0,0 +1,40 @@
+---
+title: collections.EchoParam
+linkTitle: echoParam
+description: Prints a parameter if it is set.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [echoParam]
+  returnType: any
+  signatures: [collections.EchoParam COLLECTION KEY]
+relatedFunctions: []
+aliases: [/functions/echoparam]
+---
+
+For example, consider this site configuration:
+
+{{< code-toggle file=hugo copy=false >}}
+[params.footer]
+poweredBy = 'Hugo'
+{{< /code-toggle >}}
+
+To print the value of `poweredBy`:
+
+```go-html-template
+{{ echoParam site.Params.footer "poweredby" }} → Hugo
+```
+
+{{% note %}}
+When using the `echoParam` function you must reference the key using lower case. See the previous example.
+
+The `echoParam` function will be deprecated in a future release. Instead, use either of the constructs below.
+{{% /note %}}
+
+```go-html-template
+{{ site.Params.footer.poweredBy }} → Hugo
+{{ index site.Params.footer "poweredBy" }} → Hugo
+```
--- a/docs/content/en/functions/collections/First.md
+++ b/docs/content/en/functions/collections/First.md
@@ -0,0 +1,53 @@
+---
+title: collections.First
+linkTitle: first
+description: Slices an array to the first N elements.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [first]
+  returnType: any
+  signatures: [collections.First LIMIT COLLECTION]
+relatedFunctions:
+  - collections.After
+  - collections.First
+  - collections.Last
+aliases: [/functions/first]
+---
+
+`first` works in a similar manner to the [`limit` keyword in
+SQL][limitkeyword]. It reduces the array to only the `first N`
+elements. It takes the array and number of elements as input.
+
+`first` takes two arguments:
+1. `number of elements`
+2. `array` *or* `slice of maps or structs`
+
+{{< code file="layout/_default/section.html" >}}
+{{ range first 10 .Pages }}
+    {{ .Render "summary" }}
+{{ end }}
+{{< /code >}}
+
+*Note: Exclusive to `first`, LIMIT can be '0' to return an empty array.*
+
+## `first` and `where` Together
+
+Using `first` and [`where`] together can be very
+powerful. Below snippet gets a list of posts only from [main
+sections], sorts it by the `title` parameter, and then
+ranges through only the first 5 posts in that list:
+
+{{< code file="first-and-where-together.html" >}}
+{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }}
+   {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+
+[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
+[`where`]: /functions/collections/where
+[main sections]: /functions/collections/where#mainsections
--- a/docs/content/en/functions/collections/Group.md
+++ b/docs/content/en/functions/collections/Group.md
@@ -0,0 +1,40 @@
+---
+title: collections.Group
+linkTitle: group
+description: Groups a list of pages.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [group]
+  returnType: any
+  signatures: [PAGES | collections.Group KEY]
+relatedFunctions:
+  - collections.Dictionary
+  - collections.Group
+  - collections.Index
+  - collections.IsSet
+  - collections.Where
+aliases: [/functions/group]
+---
+
+{{< code file="layouts/partials/groups.html" >}}
+{{ $new := .Site.RegularPages | first 10 | group "New" }}
+{{ $old := .Site.RegularPages | last 10 | group "Old" }}
+{{ $groups := slice $new $old }}
+{{ range $groups }}
+  <h3>{{ .Key }}{{/* Prints "New", "Old" */}}</h3>
+  <ul>
+    {{ range .Pages }}
+      <li>
+        <a href="{{ .Permalink }}">{{ .Title }}</a>
+        <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+      </li>
+    {{ end }}
+  </ul>
+{{ end }}
+{{< /code >}}
+
+The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages).
--- a/docs/content/en/functions/collections/In.md
+++ b/docs/content/en/functions/collections/In.md
@@ -0,0 +1,38 @@
+---
+title: collections.In
+linkTitle: in
+description: Reports whether an element is in an array or slice, or if a substring is in a string.
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [in]
+  returnType: bool
+  signatures: [collections.In SET ITEM]
+relatedFunctions:
+  - collections.Slice
+aliases: [/functions/in]
+---
+
+
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ in $s "b" }} → true
+```
+
+```go-html-template
+{{ $s := slice 1 2 3 }}
+{{ in $s 2 }} → true
+```
+
+```go-html-template
+{{ $s := slice 1.11 2.22 3.33 }}
+{{ in $s 2.22 }} → true
+```
+
+```go-html-template
+{{ $s := "abc" }}
+{{ in $s "b" }} → true
+```
--- a/docs/content/en/functions/collections/IndexFunction.md
+++ b/docs/content/en/functions/collections/IndexFunction.md
@@ -0,0 +1,104 @@
+---
+title: collections.Index
+linkTitle: index
+description: Looks up the index(es) or key(s) of the data structure passed into it.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [index]
+  returnType: any
+  signatures:
+    - collections.Index COLLECTION INDEXES
+    - collections.Index COLLECTION KEYS
+relatedFunctions:
+  - collections.Dictionary
+  - collections.EchoParam
+  - collections.Group
+  - collections.Index
+  - collections.IsSet
+  - collections.Where
+aliases: [/functions/index,/functions/index-function]
+---
+
+The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
+
+```go-text-template
+{{ $slice := slice "a" "b" "c" }}
+{{ index $slice 1 }} => b
+{{ $map := dict "a" 100 "b" 200 }}
+{{ index $map "b" }} => 200
+```
+
+The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
+
+```go-text-template
+{{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
+{{ index $map "c" 1 }} => 20
+{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ index $map "c" "e" }} => 20
+```
+
+You may write multiple indices as a slice:
+
+```go-text-template
+{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ $slice := slice "c" "e" }}
+{{ index $map $slice }} => 20
+```
+
+## Example: load data from a path based on front matter parameters
+
+Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:
+
+```
+.
+└── data
+    └── locations
+        ├── abilene.toml
+        ├── chicago.toml
+        ├── oslo.toml
+        └── provo.toml
+```
+
+Here is an example:
+
+{{< code-toggle file="data/locations/oslo" copy=false >}}
+website = "https://www.oslo.kommune.no"
+pop_city = 658390
+pop_metro = 1717900
+{{< /code-toggle >}}
+
+The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
+
+{{< code-toggle file="content/articles/oslo.md" fm=true copy=false >}}
+title = "My Norwegian Vacation"
+location = "oslo"
+{{< /code-toggle >}}
+
+The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter.
+
+This is where the `index` function is needed. `index` takes 2 arguments in this use case:
+
+1. The node path
+2. A string corresponding to the desired data; e.g.&mdash;
+
+```go-html-template
+{{ index .Site.Data.locations "oslo" }}
+```
+
+The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
+
+```go-html-template
+{{ index .Site.Data.locations .Params.location }}
+=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
+```
+
+Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
+
+```go-html-template
+{{ (index .Site.Data.locations .Params.location).pop_city }}
+=> 658390
+```
--- a/docs/content/en/functions/collections/Intersect.md
+++ b/docs/content/en/functions/collections/Intersect.md
@@ -0,0 +1,37 @@
+---
+title: collections.Intersect
+linkTitle: intersect
+description: Returns the common elements of two arrays or slices, in the same order as the first array.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [intersect]
+  returnType: any
+  signatures: [collections.Intersect SET1 SET2]
+relatedFunctions:
+  - collections.Complement
+  - collections.Intersect
+  - collections.SymDiff
+  - collections.Union
+aliases: [/functions/intersect]
+---
+A useful example is to use it as `AND` filters when combined with where:
+
+## AND filter in where query
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [union](/functions/collections/union) for `OR`.
+
+
+[partials]: /templates/partials/
+[single]: /templates/single-page-templates/
--- a/docs/content/en/functions/collections/IsSet.md
+++ b/docs/content/en/functions/collections/IsSet.md
@@ -0,0 +1,52 @@
+---
+title: collections.IsSet
+linkTitle: isset
+description: Reports whether the key exists within the collection.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [isset]
+  returnType: bool
+  signatures: [collections.IsSet COLLECTION KEY]
+relatedFunctions:
+  - collections.Dictionary
+  - collections.Group
+  - collections.Index
+  - collections.IsSet
+  - collections.Where
+aliases: [/functions/isset]
+---
+
+For example, consider this site configuration:
+
+{{< code-toggle file=hugo copy=false >}}
+[params]
+showHeroImage = false
+{{< /code-toggle >}}
+
+It the value of `showHeroImage` is `true`, we can detect that it exists using either `if` or `with`:
+
+```go-html-template
+{{ if site.Params.showHeroImage }}
+  {{ site.Params.showHeroImage }} → true
+{{ end }}
+
+{{ with site.Params.showHeroImage }}
+  {{ . }} → true
+{{ end }}
+```
+
+But if the value of `showHeroImage` is `false`, we can't use either `if` or `with` to detect its existence. In this case, you must use the `isset` function:
+
+```go-html-template
+{{ if isset site.Params "showheroimage" }}
+  <p>The showHeroImage parameter is set to {{ site.Params.showHeroImage }}.<p>
+{{ end }}
+```
+
+{{% note %}}
+When using the `isset` function you must reference the key using lower case. See the previous example.
+{{% /note %}}
--- a/docs/content/en/functions/collections/KeyVals.md
+++ b/docs/content/en/functions/collections/KeyVals.md
@@ -0,0 +1,45 @@
+---
+title: collections.KeyVals
+linkTitle: keyVals
+description: Returns a KeyVals struct.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [keyVals]
+  returnType: KeyValues
+  signatures: [collections.KeyVals KEY VALUES...]
+relatedFunctions: []
+aliases: [/functions/keyvals]
+---
+
+The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the `.Related` method on the `Page` object.
+
+See [related content](/content-management/related).
+
+```go-html-template
+{{ $kv := keyVals "foo" "a" "b" "c" }}
+```
+
+The resulting data structure is:
+
+```json
+{
+  "Key": "foo",
+  "Values": [
+    "a",
+    "b",
+    "c"
+  ]
+}
+```
+
+To extract the key and values:
+
+```go-html-template
+
+{{ $kv.Key }} → foo
+{{ $kv.Values }} → [a b c]
+```
--- a/docs/content/en/functions/collections/Last.md
+++ b/docs/content/en/functions/collections/Last.md
@@ -0,0 +1,25 @@
+---
+title: collections.Last
+linkTitle: last
+description: Slices an array to the last N elements.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [last]
+  returnType: any
+  signatures: [collections.Last INDEX COLLECTION]
+relatedFunctions:
+  - collections.After
+  - collections.First
+  - collections.Last
+aliases: [/functions/last]
+---
+
+```go-html-template
+{{ range last 10 .Pages }}
+  {{ .Render "summary" }}
+{{ end }}
+```
--- a/docs/content/en/functions/collections/Merge.md
+++ b/docs/content/en/functions/collections/Merge.md
@@ -0,0 +1,74 @@
+---
+title: collections.Merge
+linkTitle: merge
+description: Returns the result of merging two or more maps.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [merge]
+  returnType: any
+  signatures: [collections.Merge MAP MAP...]
+relatedFunctions:
+  - collections.Append
+  - collections.Merge
+aliases: [/functions/merge]
+---
+
+Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
+
+Key handling is case-insensitive.
+
+The following examples use these map definitions:
+
+```go-html-template
+{{ $m1 := dict "x" "foo" }}
+{{ $m2 := dict "x" "bar" "y" "wibble" }}
+{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
+```
+
+Example 1
+
+```go-html-template
+{{ $merged := merge $m1 $m2 $m3 }}
+
+{{ $merged.x }}   → baz
+{{ $merged.y }}   → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 2
+
+```go-html-template
+{{ $merged := merge $m3 $m2 $m1 }}
+
+{{ $merged.x }}   → foo
+{{ $merged.y }}   → wibble
+{{ $merged.z.a }} → huey
+```
+
+Example 3
+
+```go-html-template
+{{ $merged := merge $m2 $m3 $m1 }}
+
+{{ $merged.x }}   → foo
+{{ $merged.y }}   → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 4
+
+```go-html-template
+{{ $merged := merge $m1 $m3 $m2 }}
+
+{{ $merged.x }}   → bar
+{{ $merged.y }}   → wibble
+{{ $merged.z.a }} → huey
+```
+
+{{% note %}}
+Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
+{{% /note %}}
--- a/docs/content/en/functions/collections/NewScratch.md
+++ b/docs/content/en/functions/collections/NewScratch.md
@@ -0,0 +1,22 @@
+---
+title: collections.NewScratch
+linkTitle: newScratch
+description: Creates a new Scratch which can be used to store values in a thread safe way.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [newScratch]
+  returnType: Scratch
+  signatures: [collections.NewScratch ]
+relatedFunctions: []
+---
+
+```go-html-template
+{{ $scratch := newScratch }}
+{{ $scratch.Add "b" 2 }}
+{{ $scratch.Add "b" 2 }}
+{{ $scratch.Get "b" }} → 4
+```
--- a/docs/content/en/functions/collections/Querify.md
+++ b/docs/content/en/functions/collections/Querify.md
@@ -0,0 +1,37 @@
+---
+title: collections.Querify
+linkTitle: querify
+description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [querify]
+  returnType: string
+  signatures:
+    - collections.Querify KEY VALUE [KEY VALUE]...
+    - collections.Querify COLLECTION
+relatedFunctions:
+  - collections.Querify
+  - urlquery
+aliases: [/functions/querify]
+---
+
+`querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL.
+
+The following examples create a link to a search results page on Google.
+
+```go-html-template
+<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
+
+{{ $qs := slice "q" "test" "page" 3 }}
+<a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a>
+```
+
+Both of these examples render the following HTML:
+
+```html
+<a href="https://www.google.com?page=3&q=test">Search</a>
+```
--- a/docs/content/en/functions/collections/Reverse.md
+++ b/docs/content/en/functions/collections/Reverse.md
@@ -0,0 +1,26 @@
+---
+title: collections.Reverse
+description: Reverses the order of a collection.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: []
+  returnType: any
+  signatures: [collections.Reverse COLLECTION]
+relatedFunctions:
+  - collections.Apply
+  - collections.Delimit
+  - collections.In
+  - collections.Reverse
+  - collections.Seq
+  - collections.Slice
+aliases: [/functions/collections.reverse]
+---
+
+
+```go-html-template
+{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]
+```
--- a/docs/content/en/functions/collections/Seq.md
+++ b/docs/content/en/functions/collections/Seq.md
@@ -0,0 +1,42 @@
+---
+title: collections.Seq
+linkTitle: seq
+description: Returns a slice of integers.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [seq]
+  returnType: '[]int'
+  signatures:
+    - collections.Seq LAST
+    - collections.Seq FIRST LAST
+    - collections.Seq FIRST INCREMENT LAST
+relatedFunctions:
+  - collections.Apply
+  - collections.Delimit
+  - collections.In
+  - collections.Reverse
+  - collections.Seq
+  - collections.Slice
+aliases: [/functions/seq]
+---
+
+```go-html-template
+{{ seq 2 }} → [1 2]
+{{ seq 0 2 }} → [0 1 2]
+{{ seq -2 2 }} → [-2 -1 0 1 2]
+{{ seq -2 2 2 }} → [-2 0 2]
+```
+
+Iterate over a sequence of integers:
+
+```go-html-template
+{{ $product := 1 }}
+{{ range seq 4 }}
+  {{ $product = mul $product . }}
+{{ end }}
+{{ $product }} → 24
+```
--- a/docs/content/en/functions/collections/Shuffle.md
+++ b/docs/content/en/functions/collections/Shuffle.md
@@ -0,0 +1,28 @@
+---
+title: collections.Shuffle
+linkTitle: shuffle
+description: Returns a random permutation of a given array or slice.
+keywords: [ordering]
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [shuffle]
+  returnType: any
+  signatures: [collections.Shuffle COLLECTION]
+relatedFunctions:
+  - collections.Reverse
+  - collections.Shuffle
+  - collections.Sort
+  - collections.Uniq
+aliases: [/functions/shuffle]
+---
+
+```go-html-template
+{{ shuffle (seq 1 2 3) }} → [3 1 2] 
+{{ shuffle (slice "a" "b" "c") }} → [b a c] 
+```
+
+The result will vary from one build to the next.
--- a/docs/content/en/functions/collections/Slice.md
+++ b/docs/content/en/functions/collections/Slice.md
@@ -0,0 +1,30 @@
+---
+title: collections.Slice
+linkTitle: slice
+description: Creates a slice (array) of all passed arguments.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [slice]
+  returnType: any
+  signatures: [collections.Slice ITEM...]
+relatedFunctions:
+  - collections.Append
+  - collections.Apply
+  - collections.Delimit
+  - collections.In
+  - collections.Reverse
+  - collections.Seq
+  - collections.Slice
+aliases: [/functions/slice]
+---
+
+One use case is the concatenation of elements in combination with the [`delimit` function]:
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ $s }} → [a b c]
+```
--- a/docs/content/en/functions/collections/Sort.md
+++ b/docs/content/en/functions/collections/Sort.md
@@ -0,0 +1,135 @@
+---
+title: collections.Sort
+linkTitle: sort
+description: Sorts slices, maps, and page collections.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [sort]
+  returnType: any
+  signatures: ['collections.Sort COLLECTION [KEY] [ORDER]']
+relatedFunctions:
+  - collections.Reverse
+  - collections.Shuffle
+  - collections.Sort
+  - collections.Uniq
+aliases: [/functions/sort]
+---
+
+The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
+
+The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
+
+## Sort a slice
+
+The examples below assume this site configuration:
+
+{{< code-toggle file="hugo" copy=false >}}
+[params]
+grades = ['b','a','c']
+{{< /code-toggle >}}
+
+### Ascending order {#slice-ascending-order}
+
+Sort slice elements in ascending order using either of these constructs:
+
+{{< code file="layouts/_default/single.html" copy=false >}}
+{{ sort site.Params.grades }} → [a b c]
+{{ sort site.Params.grades "value" "asc" }} → [a b c]
+{{< /code >}}
+
+In the examples above, `value` is the `KEY` representing the value of the slice element.
+
+### Descending order {#slice-descending-order}
+
+Sort slice elements in descending order:
+
+{{< code file="layouts/_default/single.html" copy=false >}}
+{{ sort site.Params.grades "value" "desc" }} → [c b a]
+{{< /code >}}
+
+In the example above, `value` is the `KEY` representing the value of the slice element.
+
+## Sort a map
+
+The examples below assume this site configuration:
+
+{{< code-toggle file="hugo" copy=false >}}
+[params.authors.a]
+firstName = "Marius"
+lastName  = "Pontmercy"
+[params.authors.b]
+firstName = "Victor"
+lastName  = "Hugo"
+[params.authors.c]
+firstName = "Jean"
+lastName  = "Valjean"
+{{< /code-toggle >}}
+
+{{% note %}}
+When sorting maps, the `KEY` argument must be lowercase.
+{{% /note %}}
+
+### Ascending order {#map-ascending-order}
+
+Sort map objects in ascending order using either of these constructs:
+
+{{< code file="layouts/_default/single.html" copy=false >}}
+{{ range sort site.Params.authors "firstname" }}
+  {{ .firstName }}
+{{ end }}
+
+{{ range sort site.Params.authors "firstname" "asc" }}
+  {{ .firstName }}
+{{ end }}
+{{< /code >}}
+
+These produce:
+
+```text
+Jean Marius Victor
+```
+
+### Descending order {#map-descending-order}
+
+Sort map objects in descending order:
+
+{{< code file="layouts/_default/single.html" copy=false >}}
+{{ range sort site.Params.authors "firstname" "desc" }}
+  {{ .firstName }}
+{{ end }}
+{{< /code >}}
+
+This produces:
+
+```text
+Victor Marius Jean
+```
+
+## Sort a page collection
+
+Although you can use the `sort` function to sort a page collection, Hugo provides [built-in methods for sorting page collections] by:
+
+- weight
+- linktitle
+- title
+- front matter parameter
+- date
+- expiration date
+- last modified date
+- publish date
+- length
+
+In this contrived example, sort the site's regular pages by `.Type` in descending order:
+
+{{< code file="layouts/_default/home.html" copy=false >}}
+{{ range sort site.RegularPages "Type" "desc" }}
+  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+{{< /code >}}
+
+
+[built-in methods for sorting page collections]: /templates/lists/#order-content
--- a/docs/content/en/functions/collections/SymDiff.md
+++ b/docs/content/en/functions/collections/SymDiff.md
@@ -0,0 +1,28 @@
+---
+title: collections.SymDiff
+linkTitle: symdiff
+description: Returns the symmetric difference of two collections.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [symdiff]
+  returnType: any
+  signatures: [COLLECTION | collections.SymDiff COLLECTION]
+relatedFunctions:
+  - collections.Complement
+  - collections.Intersect
+  - collections.SymDiff
+  - collections.Union
+aliases: [/functions/symdiff]
+---
+
+Example:
+
+```go-html-template
+{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]
+```
+
+Also see https://en.wikipedia.org/wiki/Symmetric_difference
--- a/docs/content/en/functions/collections/Union.md
+++ b/docs/content/en/functions/collections/Union.md
@@ -0,0 +1,50 @@
+---
+title: collections.Union
+linkTitle: union
+description: Given two arrays or slices, returns a new array that contains the elements or objects that belong to either or both arrays/slices.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [union]
+  returnType: any
+  signatures: [collections.Union SET1 SET2]
+relatedFunctions:
+  - collections.Complement
+  - collections.Intersect
+  - collections.SymDiff
+  - collections.Union
+aliases: [/functions/union] 
+---
+
+Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64).
+
+```go-html-template
+{{ union (slice 1 2 3) (slice 3 4 5) }}
+<!-- returns [1 2 3 4 5] -->
+
+{{ union (slice 1 2 3) nil }}
+<!-- returns [1 2 3] -->
+
+{{ union nil (slice 1 2 3) }}
+<!-- returns [1 2 3] -->
+
+{{ union nil nil }}
+<!-- returns an error because both arrays/slices have to be of the same type -->
+```
+
+## OR filter in where query
+
+This is also very useful to use as `OR` filters when combined with where:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [intersect](/functions/collections/intersect) for `AND`.
--- a/docs/content/en/functions/collections/Uniq.md
+++ b/docs/content/en/functions/collections/Uniq.md
@@ -0,0 +1,25 @@
+---
+title: collections.Uniq
+linkTitle: uniq
+description: Takes in a slice or array and returns a slice with duplicate elements removed.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [uniq]
+  returnType: any
+  signatures: [collections.Uniq COLLECTION]
+relatedFunctions:
+  - collections.Reverse
+  - collections.Shuffle
+  - collections.Sort
+  - collections.Uniq
+aliases: [/functions/uniq]
+---
+
+
+```go-html-template
+{{ slice 1 3 2 1 | uniq }} → [1 3 2]
+```
--- a/docs/content/en/functions/collections/Where.md
+++ b/docs/content/en/functions/collections/Where.md
@@ -0,0 +1,190 @@
+---
+title: collections.Where 
+linkTitle: where
+description: Filters an array to only the elements containing a matching value for a given field.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [where]
+  returnType: any
+  signatures: ['collections.Where COLLECTION KEY [OPERATOR] MATCH']
+relatedFunctions:
+  - collections.Dictionary
+  - collections.Group
+  - collections.Index
+  - collections.IsSet
+  - collections.Where 
+aliases: [/functions/where]
+toc: true
+---
+
+`where` filters an array to only the elements containing a matching
+value for a given field.
+
+It works in a similar manner to the [`where` keyword in
+SQL][wherekeyword].
+
+```go-html-template
+{{ range where .Pages "Section" "foo" }}
+  {{ .Content }}
+{{ end }}
+```
+
+It can be used by dot-chaining the second argument to refer to a nested element of a value.
+
+{{< code-toggle file="content/example.md" fm=true copy=false >}}
+title: Example
+series: golang
+{{< /code-toggle >}}
+
+```go-html-template
+{{ range where .Site.Pages "Params.series" "golang" }}
+   {{ .Content }}
+{{ end }}
+```
+
+It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`.
+
+```go-html-template
+{{ range where .Pages "Section" "!=" "foo" }}
+   {{ .Content }}
+{{ end }}
+```
+
+The following logical operators are available with `where`:
+
+`=`, `==`, `eq`
+: `true` if a given field value equals a matching value
+
+`!=`, `<>`, `ne`
+: `true` if a given field value doesn't equal a matching value
+
+`>=`, `ge`
+: `true` if a given field value is greater than or equal to a matching value
+
+`>`, `gt`
+: `true` if a given field value is greater than a matching value
+
+`<=`, `le`
+: `true` if a given field value is lesser than or equal to a matching value
+
+`<`, `lt`
+: `true` if a given field value is lesser than a matching value
+
+`in`
+: `true` if a given field value is included in a matching value; a matching value must be an array or a slice
+
+`not in`
+: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice
+
+`intersect`
+: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect].
+
+`like`
+: `true` if a given field value matches a regular expression. Use the `like` operator to compare `string` values. Returns `false` when comparing other data types to the regular expression.
+
+## Use `where` with boolean values
+When using booleans you should not put quotation marks.
+```go-html-template
+{{ range where .Pages "Draft" true }}
+        <p>{{ .Title }}</p>
+{{ end }}
+```
+
+## Use `where` with `intersect`
+
+```go-html-template
+{{ range where .Site.Pages "Params.tags" "intersect" .Params.tags }}
+  {{ if ne .Permalink $.Permalink }}
+    {{ .Render "summary" }}
+  {{ end }}
+{{ end }}
+```
+
+You can also put the returned value of the `where` clauses into a variable:
+
+{{< code file="where-intersect-variables.html" >}}
+{{ $v1 := where .Site.Pages "Params.a" "v1" }}
+{{ $v2 := where .Site.Pages "Params.b" "v2" }}
+{{ $filtered := $v1 | intersect $v2 }}
+{{ range $filtered }}
+{{ end }}
+{{< /code >}}
+
+## Use `where` with `like`
+
+This example matches pages where the "foo" parameter begins with "ab":
+
+```go-html-template
+{{ range where site.RegularPages "Params.foo" "like" `^ab` }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+{{% readfile file="/functions/_common/regular-expressions.md" %}}
+
+## Use `where` with `first`
+
+Using `first` and `where` together can be very
+powerful. Below snippet gets a list of posts only from [**main
+sections**](#mainsections), sorts it using the [default
+ordering](/templates/lists/) for lists (i.e., `weight => date`), and
+then ranges through only the first 5 posts in that list:
+
+{{< code file="first-and-where-together.html" >}}
+{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
+   {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+## Nest `where` clauses
+
+You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured:
+
+```go-html-template
+{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }}
+```
+
+## Unset fields
+
+Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`.
+
+This can be useful to filter a small amount of pages from a large pool. Instead of setting a field on all pages, you can set that field on required pages only.
+
+Only the following operators are available for `nil`
+
+* `=`, `==`, `eq`: True if the given field is not set.
+* `!=`, `<>`, `ne`: True if the given field is set.
+
+```go-html-template
+{{ range where .Pages "Params.specialpost" "!=" nil }}
+   {{ .Content }}
+{{ end }}
+```
+
+## Portable `where` filters -- `site.Params.mainSections` {#mainsections}
+
+**This is especially important for themes.**
+
+To list the most relevant pages on the front page or similar, you
+should use the `site.Params.mainSections` list instead of comparing
+section names to hard-coded values like `"posts"` or `"post"`.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }}
+```
+
+If the user has not set this configuration parameter in their site configuration, it will default to the *section with the most pages*.
+
+The user can override the default:
+
+{{< code-toggle file="hugo" >}}
+[params]
+  mainSections = ["blog", "docs"]
+{{< /code-toggle >}}
+
+[intersect]: /functions/collections/intersect
+[wherekeyword]: https://www.techonthenet.com/sql/where.php