Merge commit '5e078383a787e8b5ec3ba73f05ea4130840afbe2'

5 files changed, 64 insertions, 27 deletions

diff --git a/docs/content/en/functions/apply.md b/docs/content/en/functions/apply.md
index 9690837d6..df22732a0 100644
--- a/docs/content/en/functions/apply.md
+++ b/docs/content/en/functions/apply.md
@@ -59,25 +59,25 @@ However, it is not possible to provide the output of a range to the [`delimit` f
 
 If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
 
-{{< code file="layouts/partial/post-tag-list.html" copy="false" >}}
+{{< 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" (index . 0) }}
+    {{ partial "post-tag-link" (index . 0) }}
   {{ else }}
     {{ $last := sub $len 1 }}
     {{ range first $last . }}
-      {{ partial "post/tag/link" . }},
+      {{ partial "post-tag-link" . }},
     {{ end }}
-    {{ partial "post/tag/link" (index . $last) }}
+    {{ partial "post-tag-link" (index . $last) }}
   {{ end }}
 </div>
 {{ end }}
 {{< /code >}}
 
-{{< code file="layouts/partial/post-tag-link.html" copy="false" >}}
+{{< code file="layouts/partials/post-tag-link.html" copy="false" >}}
 <a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
 {{< /code >}}
 
diff --git a/docs/content/en/functions/first.md b/docs/content/en/functions/first.md
index e4c0a848d..a0c7ca146 100644
--- a/docs/content/en/functions/first.md
+++ b/docs/content/en/functions/first.md
@@ -19,11 +19,36 @@ deprecated: false
 aliases: []
 ---
 
+`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`][wherefunction] together can be very
+powerful. Below snippet gets a list of posts only from [**main
+sections**][mainsections], 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
+[wherefunction]: /functions/where/
+[mainsections]: /functions/where/#mainsections
diff --git a/docs/content/en/functions/len.md b/docs/content/en/functions/len.md
index e054ed5f8..e95d49c4a 100644
--- a/docs/content/en/functions/len.md
+++ b/docs/content/en/functions/len.md
@@ -43,10 +43,11 @@ You may want to append a class to a heading according to the length of the strin
 
 ## `len` Example 2: Counting Pages with `where`
 
-The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]:
+The following templating uses [`where`][] in conjunction with `len` to
+figure out the total number of content pages in a `posts` [section][]:
 
 {{< code file="how-many-posts.html" >}}
-{{ $posts := (where .Site.RegularPages "Section" "==" "post") }}
+{{ $posts := (where .Site.RegularPages "Section" "==" "posts") }}
 {{ $postCount := len $posts }}
 {{< /code >}}
 
diff --git a/docs/content/en/functions/transform.Unmarshal.md b/docs/content/en/functions/transform.Unmarshal.md
index 7197a6eb1..571117090 100644
--- a/docs/content/en/functions/transform.Unmarshal.md
+++ b/docs/content/en/functions/transform.Unmarshal.md
@@ -7,13 +7,12 @@ menu:
   docs:
     parent: "functions"
 keywords: []
-signature: ["RESOURCE or STRING | transform.Unmarshal [OPTIONS]" ]
+signature: ["RESOURCE or STRING | transform.Unmarshal [OPTIONS]"]
 hugoversion: "0.53"
 aliases: []
 ---
 
-
-The function accept either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
+The function accept either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
 
 ```go-html-template
 {{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}`
@@ -36,15 +35,13 @@ The above prints `Hello Hugo`.
 Unmarshal with CSV as input has some options you can set:
 
 delimiter
-: The delimiter used, default is `,`
+: The delimiter used, default is `,`.
 
 comment
-: The comment character ued in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
-
+: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
 
 Example:
 
 ```go-html-template
 {{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
 ```
-
diff --git a/docs/content/en/functions/where.md b/docs/content/en/functions/where.md
index 9ad8daf2a..29623c908 100644
--- a/docs/content/en/functions/where.md
+++ b/docs/content/en/functions/where.md
@@ -20,10 +20,14 @@ toc: true
 needsexample: true
 ---
 
-`where` filters an array to only the elements containing a matching value for a given field.
+`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" "post" }}
+{{ range where .Pages "Section" "foo" }}
   {{ .Content }}
 {{ end }}
 ```
@@ -45,7 +49,7 @@ series: golang
 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" "!=" "post" }}
+{{ range where .Pages "Section" "!=" "foo" }}
    {{ .Content }}
 {{ end }}
 ```
@@ -101,10 +105,14 @@ You can also put the returned value of the `where` clauses into a variable:
 
 ## Use `where` with `first`
 
-The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
+Using `first` and [`where`][wherefunction] 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="where-with-first.html" >}}
-{{ range first 5 (where .Pages "Section" "post") }}
+{{< code file="first-and-where-together.html" >}}
+{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
    {{ .Content }}
 {{ end }}
 {{< /code >}}
@@ -134,21 +142,27 @@ Only the following operators are available for `nil`
 {{ end }}
 ```
 
-## Portable `where` filters
+## Portable `where` filters -- `site.Params.mainSections` {#mainsections}
 
-This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list.
+**This is especially important for themes.**
 
-This will, by default, list pages from the _section with the most pages_.
+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 }}
+{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }}
 ```
 
+If the user has not set this config parameter in their site config, it
+will default to the _section with the most pages_.
+
 The user can override the default in `config.toml`:
 
 ```toml
 [params]
-mainSections = ["blog", "docs"]
+  mainSections = ["blog", "docs"]
 ```
 
 [intersect]: /functions/intersect/
+[wherekeyword]: https://www.techonthenet.com/sql/where.php