mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-19 21:21:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/content/en/_common/methods/page/next-and-prev.md Normal file
View File

@@ -0,0 +1,60 @@
---
_comment: Do not remove front matter.
---
Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages according to this sorting hierarchy:
Field|Precedence|Sort direction
:--|:--|:--
[`weight`]|1|descending
[`date`]|2|descending
[`linkTitle`]|3|descending
[`path`]|4|descending
[`date`]: /methods/page/date/
[`weight`]: /methods/page/weight/
[`linkTitle`]: /methods/page/linktitle/
[`path`]: /methods/page/path/
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
For example, with this content structure:
```text
content/
├── pages/
│ ├── _index.md
│ ├── page-1.md <-- front matter: weight = 10
│ ├── page-2.md <-- front matter: weight = 20
│ └── page-3.md <-- front matter: weight = 30
└── _index.md
```
And these templates:
```go-html-template {file="layouts/_default/list.html"}
{{ range .Pages.ByWeight }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
```go-html-template {file="layouts/_default/single.html"}
{{ with .Prev }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with .Next }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}
```
When you visit page-2:
- The `Prev` method points to page-3
- The `Next` method points to page-1
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
[site configuration]: /configuration/page/
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev

78
docs/content/en/_common/methods/page/nextinsection-and-previnsection.md Normal file
View File

@@ -0,0 +1,78 @@
---
_comment: Do not remove front matter.
---
Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages according to this sorting hierarchy:
Field|Precedence|Sort direction
:--|:--|:--
[`weight`]|1|descending
[`date`]|2|descending
[`linkTitle`]|3|descending
[`path`]|4|descending
[`date`]: /methods/page/date/
[`weight`]: /methods/page/weight/
[`linkTitle`]: /methods/page/linktitle/
[`path`]: /methods/page/path/
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
For example, with this content structure:
```text
content/
├── pages/
│ ├── _index.md
│ ├── page-1.md <-- front matter: weight = 10
│ ├── page-2.md <-- front matter: weight = 20
│ └── page-3.md <-- front matter: weight = 30
└── _index.md
```
And these templates:
```go-html-template {file="layouts/_default/list.html"}
{{ range .Pages.ByWeight }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
```go-html-template {file="layouts/_default/single.html"}
{{ with .PrevInSection }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with .NextInSection }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}
```
When you visit page-2:
- The `PrevInSection` method points to page-3
- The `NextInSection` method points to page-1
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
[site configuration]: /configuration/page/
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev
## Example
Code defensively by checking for page existence:
```go-html-template
{{ with .PrevInSection }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with .NextInSection }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}
```
## Alternative
Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.

35
docs/content/en/_common/methods/page/output-format-methods.md Normal file
View File

@@ -0,0 +1,35 @@
---
_comment: Do not remove front matter.
---
### Get IDENTIFIER
(`any`) Returns the `OutputFormat` object with the given identifier.
### MediaType
(`media.Type`) Returns the media type of the output format.
### MediaType.MainType
(`string`) Returns the main type of the output format's media type.
### MediaType.SubType
(`string`) Returns the subtype of the current format's media type.
### Name
(`string`) Returns the output identifier of the output format.
### Permalink
(`string`) Returns the permalink of the page generated by the current output format.
### Rel
(`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration.
### RelPermalink
(`string`) Returns the relative permalink of the page generated by the current output format.

5
docs/content/en/_common/methods/pages/group-sort-order.md Normal file
View File

@@ -0,0 +1,5 @@
---
_comment: Do not remove front matter.
---
For the optional sort order, specify either `asc` for ascending order, or `desc` for descending order.

72
docs/content/en/_common/methods/pages/next-and-prev.md Normal file
View File

@@ -0,0 +1,72 @@
---
_comment: Do not remove front matter.
---
Hugo determines the _next_ and _previous_ page by sorting the page collection according to this sorting hierarchy:
Field|Precedence|Sort direction
:--|:--|:--
[`weight`]|1|descending
[`date`]|2|descending
[`linkTitle`]|3|descending
[`path`]|4|descending
[`date`]: /methods/page/date/
[`weight`]: /methods/page/weight/
[`linkTitle`]: /methods/page/linktitle/
[`path`]: /methods/page/path/
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
For example, with this content structure:
```text
content/
├── pages/
│ ├── _index.md
│ ├── page-1.md <-- front matter: weight = 10
│ ├── page-2.md <-- front matter: weight = 20
│ └── page-3.md <-- front matter: weight = 30
└── _index.md
```
And these templates:
```go-html-template {file="layouts/_default/list.html"}
{{ range .Pages.ByWeight }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
```go-html-template {file="layouts/_default/single.html"}
{{ $pages := .CurrentSection.Pages.ByWeight }}
{{ with $pages.Prev . }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with $pages.Next . }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}
```
When you visit page-2:
- The `Prev` method points to page-3
- The `Next` method points to page-1
To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition:
```go-html-template {file="layouts/_default/single.html"}
{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}
{{ with $pages.Prev . }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with $pages.Next . }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}
```
[`Reverse`]: /methods/pages/reverse/

6
docs/content/en/_common/methods/resource/global-page-remote-resources.md Normal file
View File

@@ -0,0 +1,6 @@
---
_comment: Do not remove front matter.
---
> [!note]
> Use this method with [global resources](g), [page resources](g), or [remote resources](g).

36
docs/content/en/_common/methods/resource/processing-spec.md Normal file
View File

@@ -0,0 +1,36 @@
---
_comment: Do not remove front matter.
---
## Process specification
The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
action
: Applicable to the [`Process`](/methods/resource/process) method only. Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions.
dimensions
: Provide width _or_ height when using the [`Resize`](/methods/resource/resize) method, else provide both width _and_ height. See&nbsp;[details](/content-management/image-processing/#dimensions).
anchor
: Use with the [`Crop`](/methods/resource/crop) and [`Fill`](/methods/resource/fill) methods. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See&nbsp;[details](/content-management/image-processing/#anchor).
rotation
: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See&nbsp;[details](/content-management/image-processing/#rotation).
target format
: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See&nbsp;[details](/content-management/image-processing/#target-format).
quality
: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See&nbsp;[details](/content-management/image-processing/#quality).
hint
: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See&nbsp;[details](/content-management/image-processing/#hint).
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
background color
: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See&nbsp;[details](/content-management/image-processing/#background-color).
resampling filter
: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See&nbsp;[details](/content-management/image-processing/#resampling-filter).

67
docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md Normal file
View File

@@ -0,0 +1,67 @@
---
_comment: Do not remove front matter.
---
Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object.
## Capture a Taxonomy object
Consider this site configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
genre = 'genres'
author = 'authors'
{{< /code-toggle >}}
And this content structure:
```text
content/
├── books/
│ ├── and-then-there-were-none.md --> genres: suspense
│ ├── death-on-the-nile.md --> genres: suspense
│ └── jamaica-inn.md --> genres: suspense, romance
│ └── pride-and-prejudice.md --> genres: romance
└── _index.md
```
To capture the "genres" `Taxonomy` object from within any template, use the [`Taxonomies`] method on a `Site` object.
```go-html-template
{{ $taxonomyObject := .Site.Taxonomies.genres }}
```
To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
```go-html-template {file="layouts/_default/taxonomy.html"}
{{ $taxonomyObject := .Data.Terms }}
```
To inspect the data structure:
```go-html-template
<pre>{{ debug.Dump $taxonomyObject }}</pre>
```
Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
```go-html-template
{{ range $term, $weightedPages := $taxonomyObject }}
<h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
<ul>
{{ range $weightedPages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
```
In the example above, the first anchor element is a link to the term page.
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
[`data`]: /methods/page/data/
[`terms`]: /methods/page/data/#in-a-taxonomy-template
[`taxonomies`]: /methods/site/taxonomies/

24
docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md Normal file
View File

@@ -0,0 +1,24 @@
---
_comment: Do not remove front matter.
---
An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.
Each element of the slice provides these methods:
Count
: (`int`) Returns the number of pages to which the term is assigned.
Page
: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
Pages
: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
Term
: (`string`) Returns the term name.
WeightedPages
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group.
[methods]: /methods/pages/