Skip to content
Permalink
Browse files

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 #720.

Also highlight the use of `site.Params.mainSections`.
  • Loading branch information...
kaushalmodi committed Jan 14, 2019
1 parent 7a56abb commit b73dcb9adc00efcfc306b0e4bf840649bd679a97
@@ -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,15 +192,15 @@ 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 */%}}
```
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

0 comments on commit b73dcb9

Please sign in to comment.
You can’t perform that action at this time.