Merge commit '5e078383a787e8b5ec3ba73f05ea4130840afbe2'

8 files changed, 36 insertions, 106 deletions

diff --git a/docs/content/en/templates/base.md b/docs/content/en/templates/base.md
index 4948f6f35..5643f8d4b 100644
--- a/docs/content/en/templates/base.md
+++ b/docs/content/en/templates/base.md
@@ -42,18 +42,18 @@ Variables are denoted by capitalized text set within `<>`. Note that Hugo's defa
 
 ### Example Base Template Lookup Order
 
-As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
+As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `posts` section. Hugo picks `layout/section/posts.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
 
-Here is the lookup order for the `post` base template:
+Here is the lookup order for the `posts` base template:
 
-1. `/layouts/section/post-baseof.html`
-2. `/themes/mytheme/layouts/section/post-baseof.html`
-3. `/layouts/post/baseof.html`
-4. `/themes/mytheme/layouts/post/baseof.html`
+1. `/layouts/section/posts-baseof.html`
+2. `/themes/mytheme/layouts/section/posts-baseof.html`
+3. `/layouts/posts/baseof.html`
+4. `/themes/mytheme/layouts/posts/baseof.html`
 5. `/layouts/section/baseof.html`
 6. `/themes/mytheme/layouts/section/baseof.html`
-7. `/layouts/_default/post-baseof.html`
-8. `/themes/mytheme/layouts/_default/post-baseof.html`
+7. `/layouts/_default/posts-baseof.html`
+8. `/themes/mytheme/layouts/_default/posts-baseof.html`
 9. `/layouts/_default/baseof.html`
 10. `/themes/mytheme/layouts/_default/baseof.html`
 
diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md
index 460a657ef..e70840b7d 100644
--- a/docs/content/en/templates/data-templates.md
+++ b/docs/content/en/templates/data-templates.md
@@ -184,7 +184,7 @@ For `getCSV`, the one-character-long separator must be placed in the first posit
       </tr>
     </thead>
     <tbody>
-    {{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
+    {{ $url := "https://example.com/finance/employee-salaries.csv" }}
     {{ $sep := "," }}
     {{ range $i, $r := getCSV $sep $url }}
       <tr>
diff --git a/docs/content/en/templates/lists.md b/docs/content/en/templates/lists.md
index 2871b181e..91df60704 100644
--- a/docs/content/en/templates/lists.md
+++ b/docs/content/en/templates/lists.md
@@ -63,7 +63,7 @@ The following is an example of a typical Hugo project directory's content:
 .
 ...
 ├── content
-|   ├── post
+|   ├── posts
 |   |   ├── _index.md
 |   |   ├── post-01.md
 |   |   └── post-02.md
@@ -73,9 +73,9 @@ The following is an example of a typical Hugo project directory's content:
 ...
 ```
 
-Using the above example, let's assume you have the following in `content/post/_index.md`:
+Using the above example, let's assume you have the following in `content/posts/_index.md`:
 
-{{< code file="content/post/_index.md" >}}
+{{< code file="content/posts/_index.md" >}}
 ---
 title: My Go Journey
 date: 2017-03-23
@@ -100,7 +100,7 @@ You can now access this `_index.md`'s' content in your list template:
         {{.Content}}
     </article>
     <ul>
-    <!-- Ranges through content/post/*.md -->
+    <!-- Ranges through content/posts/*.md -->
     {{ range .Pages }}
         <li>
             <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
@@ -113,7 +113,7 @@ You can now access this `_index.md`'s' content in your list template:
 
 This above will output the following HTML:
 
-{{< code file="example.com/post/index.html" copy="false" >}}
+{{< code file="example.com/posts/index.html" copy="false" >}}
 <!--top of your baseof code-->
 <main>
     <article>
@@ -124,8 +124,8 @@ This above will output the following HTML:
         <p>Follow my journey through this new blog.</p>
     </article>
     <ul>
-        <li><a href="/post/post-01/">Post 1</a></li>
-        <li><a href="/post/post-02/">Post 2</a></li>
+        <li><a href="/posts/post-01/">Post 1</a></li>
+        <li><a href="/posts/post-02/">Post 2</a></li>
     </ul>
 </main>
 <!--bottom of your baseof-->
@@ -164,14 +164,14 @@ The default behavior of Hugo is to pluralize list titles; hence the inflection o
 
 This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base] The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
 
-{{< code file="layouts/section/post.html" >}}
+{{< code file="layouts/section/posts.html" >}}
 {{ partial "header.html" . }}
 {{ partial "subheader.html" . }}
 <main>
   <div>
    <h1>{{ .Title }}</h1>
         <ul>
-        <!-- Renders the li.html content view for each content/post/*.md -->
+        <!-- Renders the li.html content view for each content/posts/*.md -->
             {{ range .Pages }}
                 {{ .Render "li"}}
             {{ end }}
@@ -524,49 +524,14 @@ Here is the ordering for the example that follows:
 {{ end }}
 {{< /code >}}
 
-## Filter and Limiting Lists
+## Filtering and Limiting Lists {#filtering-and-limiting-lists}
 
-Sometimes you only want to list a subset of the available content. A common is to only display “Posts” on blog's homepage. You can accomplish this with the `where` function.
+Sometimes you only want to list a subset of the available content. A
+common is to only display posts from [**main sections**][mainsections]
+on the blog's homepage.
 
-### `where`
-
-`where` works in a similar manner to the [`where` keyword in SQL][wherekeyword]. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
-
-1. `array` *or* `slice of maps or structs`
-2. `key` *or* `field name`
-3. `match value`
-
-{{< code file="layouts/_default/index.html" >}}
-{{ range where .Pages "Section" "post" }}
-   {{ .Content }}
-{{ end }}
-{{< /code >}}
-
-You can see more examples in the [functions documentation for `where`][wherefunction].
-
-### `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. `array` *or* `slice of maps or structs`
-2. `number of elements`
-
-{{< code file="layout/_default/section.html" >}}
-{{ range first 10 .Pages }}
-  {{ .Render "summary" }}
-{{ end }}
-{{< /code >}}
-
-### `first` and `where` Together
-
-Using `first` and `where` together can be very powerful:
-
-{{< code file="first-and-where-together.html" >}}
-<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts -->
-{{ range first 5 (where .Pages "Section" "post").ByTitle }}
-   {{ .Content }}
-{{ end }}
-{{< /code >}}
+See the documentation on [`where` function][wherefunction] and
+[`first` function][firstfunction] for further details.
 
 [base]: /templates/base/
 [bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
@@ -576,7 +541,6 @@ Using `first` and `where` together can be very powerful:
 [getpage]: /functions/getpage/
 [homepage]: /templates/homepage/
 [homepage]: /templates/homepage/
-[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
 [mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
 [pagevars]: /variables/page/
 [partials]: /templates/partials/
@@ -590,4 +554,5 @@ Using `first` and `where` together can be very powerful:
 [taxvars]: /variables/taxonomy/
 [views]: /templates/views/
 [wherefunction]: /functions/where/
-[wherekeyword]: https://www.techonthenet.com/sql/where.php
+[firstfunction]: /functions/first/
+[mainsections]: /functions/where/#mainsections
diff --git a/docs/content/en/templates/ordering-and-grouping.md b/docs/content/en/templates/ordering-and-grouping.md
index 2125ee6a4..078adab2c 100644
--- a/docs/content/en/templates/ordering-and-grouping.md
+++ b/docs/content/en/templates/ordering-and-grouping.md
@@ -336,44 +336,9 @@ within each group is ordered alphabetically by title.
 
 ## Filter and Limiting Lists
 
-Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function.
-
-### `where`
-
-`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
-
-1. `array` or a `slice of maps or structs`
-2. `key` or `field name`
-3. `match value`
-
-{{< code file="layouts/_default/index.html" >}}
-{{ range where .Pages "Section" "post" }}
-   {{ .Content }}
-{{ end }}
-{{< /code >}}
-
-### `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. `array` or `slice of maps or structs`
-2. `number of elements`
-
-{{< code file="layout/_default/section.html" >}}
-{{ range first 10 .Pages }}
-  {{ .Render "summary" }}
-{{ end }}
-{{< /code >}}
-
-### `first` and `where` Together
-
-Using `first` and `where` together can be very powerful:
-
-{{< code file="first-and-where-together.html" >}}
-{{ range first 5 (where .Pages "Section" "post") }}
-   {{ .Content }}
-{{ end }}
-{{< /code >}}
+See the [_Lists/Filtering and Limiting Lists_
+section][filteringandlimitinglists] for details.
 
 
 [views]: /templates/views/
+[filteringandlimitinglists]: /templates/lists/#filtering-and-limiting-lists
diff --git a/docs/content/en/templates/pagination.md b/docs/content/en/templates/pagination.md
index 2ea1daae9..bd4176761 100644
--- a/docs/content/en/templates/pagination.md
+++ b/docs/content/en/templates/pagination.md
@@ -50,7 +50,7 @@ For a given **Page**, it's one of the options above. The `.Paginator` is static
 The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
 
 * `{{ range (.Paginator 5).Pages }}`
-* `{{ $paginator := .Paginate (where .Pages "Type" "post") 5 }}`
+* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}`
 
 It is also possible to use the `GroupBy` functions in combination with pagination:
 
@@ -75,7 +75,7 @@ If you use any filters or ordering functions to create your `.Paginator` *and* y
 The following example shows how to create `.Paginator` before its used:
 
 ```
-{{ $paginator := .Paginate (where .Pages "Type" "post") }}
+{{ $paginator := .Paginate (where .Pages "Type" "posts") }}
 {{ template "_internal/pagination.html" . }}
 {{ range $paginator.Pages }}
    {{ .Title }}
diff --git a/docs/content/en/templates/single-page-templates.md b/docs/content/en/templates/single-page-templates.md
index 79e1312b2..e8b72e598 100644
--- a/docs/content/en/templates/single-page-templates.md
+++ b/docs/content/en/templates/single-page-templates.md
@@ -26,11 +26,11 @@ See [Template Lookup](/templates/lookup-order/).
 
 Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
 
-### `post/single.html`
+### `posts/single.html`
 
 This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
 
-{{< code file="layouts/post/single.html" download="single.html" >}}
+{{< code file="layouts/posts/single.html" download="single.html" >}}
 {{ define "main" }}
 <section id="main">
   <h1 id="title">{{ .Title }}</h1>
diff --git a/docs/content/en/templates/taxonomy-templates.md b/docs/content/en/templates/taxonomy-templates.md
index d1f9e380f..c827376c2 100644
--- a/docs/content/en/templates/taxonomy-templates.md
+++ b/docs/content/en/templates/taxonomy-templates.md
@@ -238,7 +238,7 @@ Because we are leveraging the front matter system to define taxonomies for conte
 <ul id="{{ $taxo }}">
     {{ range .Param $taxo }}
         {{ $name := . }}
-        {{ with $.Site.GetPage (printf "/%s/%s" $taxo $name) }}
+        {{ with $.Site.GetPage (printf "/%s/%s" $taxo ($name | urlize)) }}
             <li><a href="{{ .Permalink }}">{{ $name }}</a></li>
         {{ end }}
     {{ end }}
diff --git a/docs/content/en/templates/views.md b/docs/content/en/templates/views.md
index b1a6451b2..eb158eed0 100644
--- a/docs/content/en/templates/views.md
+++ b/docs/content/en/templates/views.md
@@ -27,11 +27,11 @@ The following are common use cases for content views:
 
 ## Create a Content View
 
-To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
+To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
 
 ```
   ▾ layouts/
-    ▾ post/
+    ▾ posts/
         li.html
         single.html
         summary.html