diff options
Diffstat (limited to 'docs/content/en/_common/methods')
9 files changed, 383 insertions, 0 deletions
diff --git a/docs/content/en/_common/methods/page/next-and-prev.md b/docs/content/en/_common/methods/page/next-and-prev.md new file mode 100644 index 000000000..f859961a4 --- /dev/null +++ b/docs/content/en/_common/methods/page/next-and-prev.md @@ -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 diff --git a/docs/content/en/_common/methods/page/nextinsection-and-previnsection.md b/docs/content/en/_common/methods/page/nextinsection-and-previnsection.md new file mode 100644 index 000000000..54d240eb4 --- /dev/null +++ b/docs/content/en/_common/methods/page/nextinsection-and-previnsection.md @@ -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. diff --git a/docs/content/en/_common/methods/page/output-format-methods.md b/docs/content/en/_common/methods/page/output-format-methods.md new file mode 100644 index 000000000..1e914db03 --- /dev/null +++ b/docs/content/en/_common/methods/page/output-format-methods.md @@ -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. diff --git a/docs/content/en/_common/methods/pages/group-sort-order.md b/docs/content/en/_common/methods/pages/group-sort-order.md new file mode 100644 index 000000000..e2997a1bd --- /dev/null +++ b/docs/content/en/_common/methods/pages/group-sort-order.md @@ -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. diff --git a/docs/content/en/_common/methods/pages/next-and-prev.md b/docs/content/en/_common/methods/pages/next-and-prev.md new file mode 100644 index 000000000..462545c3f --- /dev/null +++ b/docs/content/en/_common/methods/pages/next-and-prev.md @@ -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/ diff --git a/docs/content/en/_common/methods/resource/global-page-remote-resources.md b/docs/content/en/_common/methods/resource/global-page-remote-resources.md new file mode 100644 index 000000000..49146aed4 --- /dev/null +++ b/docs/content/en/_common/methods/resource/global-page-remote-resources.md @@ -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). diff --git a/docs/content/en/_common/methods/resource/processing-spec.md b/docs/content/en/_common/methods/resource/processing-spec.md new file mode 100644 index 000000000..395217328 --- /dev/null +++ b/docs/content/en/_common/methods/resource/processing-spec.md @@ -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 [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 [details](/content-management/image-processing/#anchor). + +rotation +: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). + +target format +: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [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 [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 [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 [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 [details](/content-management/image-processing/#resampling-filter). diff --git a/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md b/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md new file mode 100644 index 000000000..6fb729c17 --- /dev/null +++ b/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md @@ -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/ diff --git a/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md b/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md new file mode 100644 index 000000000..ec5f8e406 --- /dev/null +++ b/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md @@ -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/ |