mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-08 12:25:55 -04:00
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`.
This commit is contained in:
Kaushal Modi
parent
7a56abbcec
commit
b73dcb9adc
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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/<DIRECTORIES>`) 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/<DIRECTORIES>`) 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/).
|
||||
|
||||
@ -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 `<meta name="robots" content="noindex">` 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/
|
||||
|
||||
@ -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" */%}}
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
{{%/* /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" >}}
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
{{< /output >}} -->
|
||||
|
||||
@ -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 >}}
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 >}}
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 }}
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user