From b73dcb9adc00efcfc306b0e4bf840649bd679a97 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Mon, 14 Jan 2019 12:40:10 -0500 Subject: [PATCH] Consistently use "posts" as section name in examples While Hugo does not care if the section is named "post" or "posts", this commit normalizes the whole Hugo documentation to use "posts" when used as an example for a section name to prevent user confusion. Fixes https://github.com/gohugoio/hugoDocs/issues/720. Also highlight the use of `site.Params.mainSections`. --- content/en/content-management/archetypes.md | 4 +- .../content-management/organization/index.md | 14 ++-- content/en/content-management/urls.md | 26 +++---- content/en/contribute/documentation.md | 4 +- content/en/functions/apply.md | 10 +-- content/en/functions/first.md | 29 +++++++- content/en/functions/len.md | 5 +- content/en/functions/where.md | 36 +++++++--- content/en/getting-started/code-toggle.md | 4 +- content/en/getting-started/configuration.md | 8 +-- .../deployment-with-rsync.md | 4 +- .../hosting-on-bitbucket.md | 2 +- content/en/templates/base.md | 16 ++--- content/en/templates/lists.md | 69 +++++-------------- content/en/templates/ordering-and-grouping.md | 41 +---------- content/en/templates/pagination.md | 4 +- content/en/templates/single-page-templates.md | 4 +- content/en/templates/views.md | 4 +- .../en/troubleshooting/build-performance.md | 6 +- content/en/variables/page.md | 2 +- content/zh/templates/base.md | 16 ++--- 21 files changed, 139 insertions(+), 169 deletions(-) diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index 3fc8a9f3f..354ef0fef 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -85,10 +85,10 @@ archetypes ``` ```bash -hugo new --kind post-bundle post/my-post +hugo new --kind post-bundle posts/my-post ``` -Will create a new folder in `/content/post/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. +Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md index b1bc8b368..e9ae91b57 100644 --- a/content/en/content-management/organization/index.md +++ b/content/en/content-management/organization/index.md @@ -19,7 +19,7 @@ toc: true ## Page Bundles -Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. +Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture. @@ -38,7 +38,7 @@ The bundle documentation is **work in progress**. We will publish more comprehen In Hugo, your content should be organized in a manner that reflects the rendered website. -While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][]. +While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][]. Without any additional configuration, the following will just work: @@ -47,11 +47,11 @@ Without any additional configuration, the following will just work: └── content └── about | └── _index.md // <- https://example.com/about/ - ├── post - | ├── firstpost.md // <- https://example.com/post/firstpost/ + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost/ | ├── happy - | | └── ness.md // <- https://example.com/post/happy/ness/ - | └── secondpost.md // <- https://example.com/post/secondpost/ + | | └── ness.md // <- https://example.com/posts/happy/ness/ + | └── secondpost.md // <- https://example.com/posts/secondpost/ └── quote ├── first.md // <- https://example.com/quote/first/ └── second.md // <- https://example.com/quote/second/ @@ -64,7 +64,7 @@ The following demonstrates the relationships between your content organization a ### Index Pages: `_index.md` -`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. +`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. {{% note %}} **Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index ae58a6277..25bd09165 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -27,16 +27,16 @@ The `permalinks` option in your [site configuration][config] allows you to adjus These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). {{% /note %}} -For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. +For example, if one of your [sections][] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. ### Permalinks Configuration Example {{< code-toggle file="config" copy="false" >}} permalinks: - post: /:year/:month/:title/ + posts: /:year/:month/:title/ {{< /code-toggle >}} -Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. +Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`. @@ -156,7 +156,7 @@ Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `` lets search engine bots know that they should not crawl and index your new alias page. -### Customize +### Customize You may customize this alias page by creating an `alias.html` template in the layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is @@ -199,11 +199,11 @@ See [Content Organization][contentorg] for more details on paths. └── content └── about | └── _index.md // <- https://example.com/about/ - ├── post - | ├── firstpost.md // <- https://example.com/post/firstpost/ + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost/ | ├── happy - | | └── ness.md // <- https://example.com/post/happy/ness/ - | └── secondpost.md // <- https://example.com/post/secondpost/ + | | └── ness.md // <- https://example.com/posts/happy/ness/ + | └── secondpost.md // <- https://example.com/posts/secondpost/ └── quote ├── first.md // <- https://example.com/quote/first/ └── second.md // <- https://example.com/quote/second/ @@ -216,11 +216,11 @@ Here's the same organization run with `hugo --uglyURLs`: └── content └── about | └── _index.md // <- https://example.com/about.html - ├── post - | ├── firstpost.md // <- https://example.com/post/firstpost.html + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost.html | ├── happy - | | └── ness.md // <- https://example.com/post/happy/ness.html - | └── secondpost.md // <- https://example.com/post/secondpost.html + | | └── ness.md // <- https://example.com/posts/happy/ness.html + | └── secondpost.md // <- https://example.com/posts/secondpost.html └── quote ├── first.md // <- https://example.com/quote/first.html └── second.md // <- https://example.com/quote/second.html @@ -265,7 +265,7 @@ By default, all relative URLs are left unchanged by Hugo, which can be problemat Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. -For example, if your `/post/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. +For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. [config]: /getting-started/configuration/ [contentorg]: /content-management/organization/ diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 7b198a4ca..0e97aba1a 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -192,7 +192,7 @@ The output of this example will render to the Hugo docs as follows: The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode: ``` -{{%/* output file="post/my-first-post/index.html" */%}} +{{%/* output file="posts/my-first-post/index.html" */%}}

This is my First Hugo Blog Post

I am excited to be using Hugo.

{{%/* /output */%}} @@ -200,7 +200,7 @@ The `output` shortcode is almost identical to the `code` shortcode but only take The preceding `output` example will render as follows to the Hugo docs: -{{< output file="post/my-first-post/index.html" >}} +{{< output file="posts/my-first-post/index.html" >}}

This is my First Hugo Blog Post

I am excited to be using Hugo.

{{< /output >}} --> diff --git a/content/en/functions/apply.md b/content/en/functions/apply.md index 9690837d6..df22732a0 100644 --- a/content/en/functions/apply.md +++ b/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 }}
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 }}
{{ end }} {{< /code >}} -{{< code file="layouts/partial/post-tag-link.html" copy="false" >}} +{{< code file="layouts/partials/post-tag-link.html" copy="false" >}} {{ . }} {{< /code >}} diff --git a/content/en/functions/first.md b/content/en/functions/first.md index e4c0a848d..a0c7ca146 100644 --- a/content/en/functions/first.md +++ b/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/content/en/functions/len.md b/content/en/functions/len.md index e054ed5f8..e95d49c4a 100644 --- a/content/en/functions/len.md +++ b/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/content/en/functions/where.md b/content/en/functions/where.md index 9ad8daf2a..74e9b602b 100644 --- a/content/en/functions/where.md +++ b/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 diff --git a/content/en/getting-started/code-toggle.md b/content/en/getting-started/code-toggle.md index 51c887a47..c15391b04 100644 --- a/content/en/getting-started/code-toggle.md +++ b/content/en/getting-started/code-toggle.md @@ -12,7 +12,7 @@ toc: true ## The Config Toggler! -This is an example for the Config Toggle shortcode. +This is an example for the Config Toggle shortcode. Its purpose is to let users choose a Config language by clicking on its corresponding tab. Upon doing so, every Code toggler on the page will be switched to the target language. Also, target language will be saved in user's `localStorage` so when they go to a different pages, Code Toggler display their last "toggled" config language. {{% note %}} @@ -27,7 +27,7 @@ baseURL: "https://yoursite.example.com/" title: "My Hugo Site" footnoteReturnLinkContents: "↩" permalinks: - post: /:year/:month/:title/ + posts: /:year/:month/:title/ params: Subtitle: "Hugo is Absurdly Fast!" AuthorName: "Jon Doe" diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 50a78a817..b1dac1faa 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -195,7 +195,7 @@ related relativeURLs (false) : Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. -refLinksErrorLevel ("ERROR") +refLinksErrorLevel ("ERROR") : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this logg level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). refLinksNotFoundURL @@ -280,7 +280,7 @@ baseURL: "https://yoursite.example.com/" title: "My Hugo Site" footnoteReturnLinkContents: "↩" permalinks: - post: /:year/:month/:title/ + posts: /:year/:month/:title/ params: Subtitle: "Hugo is Absurdly Fast!" AuthorName: "Jon Doe" @@ -430,7 +430,7 @@ maxAge = -1 ``` -You can override any of these cache setting in your own `config.toml`. +You can override any of these cache setting in your own `config.toml`. ### The keywords explained @@ -445,7 +445,7 @@ You can override any of these cache setting in your own `config.toml`. maxAge : This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). - + dir : The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). diff --git a/content/en/hosting-and-deployment/deployment-with-rsync.md b/content/en/hosting-and-deployment/deployment-with-rsync.md index e8222ad54..8d0137ad7 100644 --- a/content/en/hosting-and-deployment/deployment-with-rsync.md +++ b/content/en/hosting-and-deployment/deployment-with-rsync.md @@ -125,8 +125,8 @@ cours-versailles/index.html exercices/index.html exercices/index.xml exercices/barycentre-et-carres-des-distances/index.html -post/ -post/index.html +posts/ +posts/index.html sujets/index.html sujets/index.xml sujets/2016-09_supelec-jp/index.html diff --git a/content/en/hosting-and-deployment/hosting-on-bitbucket.md b/content/en/hosting-and-deployment/hosting-on-bitbucket.md index f66abed5d..03710690e 100644 --- a/content/en/hosting-and-deployment/hosting-on-bitbucket.md +++ b/content/en/hosting-and-deployment/hosting-on-bitbucket.md @@ -120,7 +120,7 @@ aero apikey ### Step 3: Edit and Commit Code ``` -hugo new post/good-to-great.md +hugo new posts/good-to-great.md hugo server --buildDrafts -t liquorice #Check that all looks good # commit and push code to master branch diff --git a/content/en/templates/base.md b/content/en/templates/base.md index 4948f6f35..5643f8d4b 100644 --- a/content/en/templates/base.md +++ b/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/content/en/templates/lists.md b/content/en/templates/lists.md index 2871b181e..91df60704 100644 --- a/content/en/templates/lists.md +++ b/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}}
    - + {{ range .Pages }}
  • {{.Date.Format "2006-01-02"}} | {{.Title}} @@ -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" >}}
    @@ -124,8 +124,8 @@ This above will output the following HTML:

    Follow my journey through this new blog.

    @@ -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" . }}

    {{ .Title }}

      - + {{ 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" >}} - -{{ 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/content/en/templates/ordering-and-grouping.md b/content/en/templates/ordering-and-grouping.md index 2125ee6a4..078adab2c 100644 --- a/content/en/templates/ordering-and-grouping.md +++ b/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/content/en/templates/pagination.md b/content/en/templates/pagination.md index 2ea1daae9..bd4176761 100644 --- a/content/en/templates/pagination.md +++ b/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/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md index 79e1312b2..e8b72e598 100644 --- a/content/en/templates/single-page-templates.md +++ b/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" }}

      {{ .Title }}

      diff --git a/content/en/templates/views.md b/content/en/templates/views.md index b1a6451b2..eb158eed0 100644 --- a/content/en/templates/views.md +++ b/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 diff --git a/content/en/troubleshooting/build-performance.md b/content/en/troubleshooting/build-performance.md index f2242ea2e..bc75ce262 100644 --- a/content/en/troubleshooting/build-performance.md +++ b/content/en/troubleshooting/build-performance.md @@ -58,17 +58,17 @@ Template Metrics: ---------- -------- -------- ----- -------- 6.419663ms 583.605µs 994.374µs 11 _internal/_default/rss.xml 4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html - 4.642666ms 2.321333ms 3.282842ms 2 post/single.html + 4.642666ms 2.321333ms 3.282842ms 2 posts/single.html 4.364445ms 396.767µs 2.451372ms 11 partials/header.html 2.346069ms 586.517µs 903.343µs 4 indexes/tag.html 2.330919ms 211.901µs 2.281342ms 11 partials/header.includes.html - 1.238976ms 103.248µs 446.084µs 12 post/li.html + 1.238976ms 103.248µs 446.084µs 12 posts/li.html 972.16µs 972.16µs 972.16µs 1 _internal/_default/sitemap.xml 953.597µs 953.597µs 953.597µs 1 index.html 822.263µs 822.263µs 822.263µs 1 indexes/post.html 567.498µs 51.59µs 112.205µs 11 partials/navbar.html 348.22µs 31.656µs 88.249µs 11 partials/meta.html - 346.782µs 173.391µs 276.176µs 2 post/summary.html + 346.782µs 173.391µs 276.176µs 2 posts/summary.html 235.184µs 21.38µs 124.383µs 11 partials/footer.copyright.html 132.003µs 12µs 117.999µs 11 partials/menu.html 72.547µs 6.595µs 63.764µs 11 partials/footer.html diff --git a/content/en/variables/page.md b/content/en/variables/page.md index 12b5d6bda..9dcbdcc43 100644 --- a/content/en/variables/page.md +++ b/content/en/variables/page.md @@ -175,7 +175,7 @@ http://remarkjs.com) : a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. .Type -: the [content type](/content-management/types/) of the content (e.g., `post`). +: the [content type](/content-management/types/) of the content (e.g., `posts`). .UniqueID : the MD5-checksum of the content file's path. diff --git a/content/zh/templates/base.md b/content/zh/templates/base.md index 4845f608f..689a54408 100644 --- a/content/zh/templates/base.md +++ b/content/zh/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`