mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-16 20:53:59 +02:00
Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs'
``` git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash ``` Closes #11925
This commit is contained in:
Bjørn Erik Pedersen
13
docs/content/en/methods/_common/_index.md
Normal file
13
docs/content/en/methods/_common/_index.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Next` and `Prev` methods on a `Page` object.
|
||||
|
||||
||Page collection|Custom sort order
|
||||
:--|:--|:-:
|
||||
[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️
|
||||
[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌
|
||||
|
||||
[`PAGES.Next`]: /methods/pages/next
|
||||
[`PAGES.Prev`]: /methods/pages/prev
|
||||
[`PAGE.Next`]: /methods/page/next
|
||||
[`PAGE.Prev`]: /methods/page/prev
|
||||
|
||||
locally defined
|
||||
: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection.
|
||||
|
||||
With a local collection, the navigation sort order is the same as the collection sort order.
|
||||
|
||||
globally defined
|
||||
: Build the page collection once, on a list page. Navigation between pages is relative to the current page's position within the global collection.
|
||||
|
||||
With a global collection, the navigation sort order is fixed, using Hugo's default sort order. In order of precedence:
|
||||
|
||||
1. Page [weight]
|
||||
2. Page [date] (descending)
|
||||
3. Page [linkTitle], falling back to page [title]
|
||||
4. Page file path if the page is backed by a file
|
||||
|
||||
For example, with a global collection sorted by title, the navigation sort order will use Hugo's default sort order. This is probably not what you want or expect. For this reason, the `Next` and `Prev` methods on a `Pages` object are generally a better choice.
|
||||
|
||||
[date]: /methods/page/date
|
||||
[weight]: /methods/page/weight
|
||||
[linkTitle]: /methods/page/linktitle
|
||||
[title]: /methods/page/title
|
||||
16
docs/content/en/methods/_index.md
Normal file
16
docs/content/en/methods/_index.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Methods
|
||||
linkTitle: Overview
|
||||
description: A list of Hugo template methods including examples.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: methods-overview
|
||||
parent: methods
|
||||
weight: 10
|
||||
weight: 10
|
||||
showSectionMenu: true
|
||||
---
|
||||
|
||||
Use these methods within your templates.
|
||||
17
docs/content/en/methods/duration/Abs.md
Normal file
17
docs/content/en/methods/duration/Abs.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Abs
|
||||
description: Returns the absolute value of the given time.Duration value.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: time.Duration
|
||||
signatures: [DURATION.Abs]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "-3h" }}
|
||||
{{ $d.Abs }} → 3h0m0s
|
||||
```
|
||||
17
docs/content/en/methods/duration/Hours.md
Normal file
17
docs/content/en/methods/duration/Hours.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Hours
|
||||
description: Returns the time.Duration value as a floating point number of hours.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: float64
|
||||
signatures: [DURATION.Hours]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Hours }} → 3.5420833333333333
|
||||
```
|
||||
17
docs/content/en/methods/duration/Microseconds.md
Normal file
17
docs/content/en/methods/duration/Microseconds.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Microseconds
|
||||
description: Returns the time.Duration value as an integer microsecond count.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: int64
|
||||
signatures: [DURATION.Microseconds]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Microseconds }} → 12751500000
|
||||
```
|
||||
17
docs/content/en/methods/duration/Milliseconds.md
Normal file
17
docs/content/en/methods/duration/Milliseconds.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Milliseconds
|
||||
description: Returns the time.Duration value as an integer millisecond count.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: int64
|
||||
signatures: [DURATION.Milliseconds]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Milliseconds }} → 12751500
|
||||
```
|
||||
17
docs/content/en/methods/duration/Minutes.md
Normal file
17
docs/content/en/methods/duration/Minutes.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Minutes
|
||||
description: Returns the time.Duration value as a floating point number of minutes.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: float64
|
||||
signatures: [DURATION.Minutes]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Minutes }} → 212.525
|
||||
```
|
||||
17
docs/content/en/methods/duration/Nanoseconds.md
Normal file
17
docs/content/en/methods/duration/Nanoseconds.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Nanoseconds
|
||||
description: Returns the time.Duration value as an integer nanosecond count.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: int64
|
||||
signatures: [DURATION.Nanoseconds]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Nanoseconds }} → 12751500000000
|
||||
```
|
||||
20
docs/content/en/methods/duration/Round.md
Normal file
20
docs/content/en/methods/duration/Round.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Round
|
||||
description: Returns the result of rounding DURATION1 to the nearest multiple of DURATION2.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType:
|
||||
signatures: [DURATION1.Round DURATION2]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
|
||||
{{ $d.Round (time.ParseDuration "2h") }} → 4h0m0s
|
||||
{{ $d.Round (time.ParseDuration "3m") }} → 3h33m0s
|
||||
{{ $d.Round (time.ParseDuration "4s") }} → 3h32m32s
|
||||
```
|
||||
17
docs/content/en/methods/duration/Seconds.md
Normal file
17
docs/content/en/methods/duration/Seconds.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Seconds
|
||||
description: Returns the time.Duration value as a floating point number of seconds.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: float64
|
||||
signatures: [DURATION.Seconds]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
{{ $d.Seconds }} → 12751.5
|
||||
```
|
||||
21
docs/content/en/methods/duration/Truncate.md
Normal file
21
docs/content/en/methods/duration/Truncate.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Truncate
|
||||
description: Returns the result of rounding DURATION1 toward zero to a multiple of DURATION2.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
related:
|
||||
- functions/time/Duration
|
||||
- functions/time/ParseDuration
|
||||
returnType: time.Duration
|
||||
signatures: [DURATION1.Truncate DURATION2]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
|
||||
|
||||
{{ $d.Truncate (time.ParseDuration "2h") }} → 2h0m0s
|
||||
{{ $d.Truncate (time.ParseDuration "3m") }} → 3h30m0s
|
||||
{{ $d.Truncate (time.ParseDuration "4s") }} → 3h32m28s
|
||||
```
|
||||
12
docs/content/en/methods/duration/_index.md
Normal file
12
docs/content/en/methods/duration/_index.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Duration methods
|
||||
linkTitle: Duration
|
||||
description: Use these methods with time.Duration values.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: methods
|
||||
---
|
||||
|
||||
Use these methods with time.Duration values.
|
||||
67
docs/content/en/methods/menu-entry/Children.md
Normal file
67
docs/content/en/methods/menu-entry/Children.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Children
|
||||
description: Returns a collection of child menu entries, if any, under the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/menu-entry/HasChildren
|
||||
returnType: navigation.Menu
|
||||
signatures: [MENUENTRY.Children]
|
||||
---
|
||||
|
||||
Use the `Children` method when rendering a nested menu.
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/product'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 1'
|
||||
pageRef = '/products/product-1'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 2'
|
||||
pageRef = '/products/product-2'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li>
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ if .HasChildren }}
|
||||
<ul>
|
||||
{{ range .Children }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this HTML:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/products/">Products</a>
|
||||
<ul>
|
||||
<li><a href="/products/product-1/">Product 1</a></li>
|
||||
<li><a href="/products/product-2/">Product 2</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
```
|
||||
67
docs/content/en/methods/menu-entry/HasChildren.md
Normal file
67
docs/content/en/methods/menu-entry/HasChildren.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: HasChildren
|
||||
description: Reports whether the given menu entry has child menu entries.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/menu-entry/Children
|
||||
returnType: bool
|
||||
signatures: [MENUENTRY.HasChildren]
|
||||
---
|
||||
|
||||
Use the `HasChildren` method when rendering a nested menu.
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/product'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 1'
|
||||
pageRef = '/products/product-1'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 2'
|
||||
pageRef = '/products/product-2'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li>
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ if .HasChildren }}
|
||||
<ul>
|
||||
{{ range .Children }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this HTML:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/products/">Products</a>
|
||||
<ul>
|
||||
<li><a href="/products/product-1/">Product 1</a></li>
|
||||
<li><a href="/products/product-2/">Product 2</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
```
|
||||
44
docs/content/en/methods/menu-entry/Identifier.md
Normal file
44
docs/content/en/methods/menu-entry/Identifier.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Identifier
|
||||
description: Returns the `identifier` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.Identifier]
|
||||
---
|
||||
|
||||
The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section.
|
||||
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
identifier = 'about'
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
identifier = 'contact'
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This example uses the `Identifier` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ or (T .Identifier) .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
|
||||
|
||||
[details]: /content-management/menus/#properties-front-matter
|
||||
{{% /note %}}
|
||||
39
docs/content/en/methods/menu-entry/KeyName.md
Normal file
39
docs/content/en/methods/menu-entry/KeyName.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: KeyName
|
||||
description: Returns the `identifier` property of the given menu entry, falling back to its `name` property.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.KeyName]
|
||||
---
|
||||
|
||||
In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
identifier = 'about'
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This example uses the `KeyName` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ or (T (.KeyName | lower)) .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase.
|
||||
|
||||
[`lower`]: functions/strings/tolower
|
||||
24
docs/content/en/methods/menu-entry/Menu.md
Normal file
24
docs/content/en/methods/menu-entry/Menu.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Menu
|
||||
description: Returns the identifier of the menu that contains the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsMenuCurrent
|
||||
- methods/page/HasMenuCurrent
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.Menu]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.Menus.main }}
|
||||
{{ .Menu }} → main
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example].
|
||||
|
||||
[`HasMenuCurrent`]: /methods/page/hasmenucurrent
|
||||
[`IsMenuCurrent`]: /methods/page/ismenucurrent
|
||||
[this example]: /templates/menu-templates/#example
|
||||
28
docs/content/en/methods/menu-entry/Name.md
Normal file
28
docs/content/en/methods/menu-entry/Name.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Name
|
||||
description: Returns the `name` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.Name]
|
||||
---
|
||||
|
||||
If you define the menu entry [automatically], the `Name` method returns the page’s [`LinkTitle`], falling back to its [`Title`].
|
||||
|
||||
If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`.
|
||||
|
||||
[`LinkTitle`]: /methods/page/linktitle
|
||||
[`Title`]: /methods/page/title
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
53
docs/content/en/methods/menu-entry/Page.md
Normal file
53
docs/content/en/methods/menu-entry/Page.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Page
|
||||
description: Returns the Page object associated with the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: page.Page
|
||||
signatures: [MENUENTRY.Page]
|
||||
---
|
||||
|
||||
Regardless of how you [define menu entries], an entry associated with a page has access to its [methods].
|
||||
|
||||
In this menu definition, the first two entries are associated with a page, the last entry is not:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
pageRef = '/about'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
pageRef = '/contact'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hugo'
|
||||
url = 'https://gohugo.io'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`] and [`LinkTitle`] when rendering the anchor element.
|
||||
|
||||
If the entry is not associated with a page, we use its `url` and `name` properties.
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
{{ with .Page }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
|
||||
{{ else }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
See the [menu templates] section for more information.
|
||||
|
||||
[`LinkTitle`]: /methods/page/linktitle
|
||||
[`RelPermalink`]: /methods/page/relpermalink
|
||||
[define menu entries]: /content-management/menus/
|
||||
[menu templates]: /templates/menu-templates/#page-references
|
||||
[methods]: /methods/page
|
||||
62
docs/content/en/methods/menu-entry/Params.md
Normal file
62
docs/content/en/methods/menu-entry/Params.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Params
|
||||
description: Returns the `params` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: maps.Params
|
||||
signatures: [MENUENTRY.Params]
|
||||
---
|
||||
|
||||
When you define menu entries [in site configuration] or [in front matter], you can include a `params` key to attach additional information to the entry. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hugo'
|
||||
url = 'https://gohugo.io'
|
||||
weight = 30
|
||||
[menus.main.params]
|
||||
rel = 'external'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
With this template:
|
||||
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li>
|
||||
<a href="{{ .URL }}" {{ with .Params.rel }}rel="{{ . }}"{{ end }}>
|
||||
{{ .Name }}
|
||||
</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/about/">About</a></li>
|
||||
<li><a href="/contact/">Contact</a></li>
|
||||
<li><a href="https://gohugo.io" rel="external">Hugo</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
See the [menu templates] section for more information.
|
||||
|
||||
[menu templates]: /templates/menu-templates/#menu-entry-parameters
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/
|
||||
50
docs/content/en/methods/menu-entry/Parent.md
Normal file
50
docs/content/en/methods/menu-entry/Parent.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Parent
|
||||
description: Returns the `parent` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.Parent]
|
||||
---
|
||||
|
||||
With this menu definition:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/product'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 1'
|
||||
pageRef = '/products/product-1'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Product 2'
|
||||
pageRef = '/products/product-2'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This template renders the nested menu, listing the `parent` property next each of the child entries:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li>
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ if .HasChildren }}
|
||||
<ul>
|
||||
{{ range .Children }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
13
docs/content/en/methods/menu-entry/Post.md
Normal file
13
docs/content/en/methods/menu-entry/Post.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Post
|
||||
description: Returns the `post` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/menu-entry/Pre
|
||||
returnType: template.HTML
|
||||
signatures: [MENUENTRY.Post]
|
||||
---
|
||||
|
||||
{{% include "methods/menu-entry/_common/pre-post.md" %}}
|
||||
13
docs/content/en/methods/menu-entry/Pre.md
Normal file
13
docs/content/en/methods/menu-entry/Pre.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Pre
|
||||
description: Returns the `pre` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/menu-entry/Post
|
||||
returnType: template.HTML
|
||||
signatures: [MENUENTRY.Pre]
|
||||
---
|
||||
|
||||
{{% include "methods/menu-entry/_common/pre-post.md" %}}
|
||||
28
docs/content/en/methods/menu-entry/Title.md
Normal file
28
docs/content/en/methods/menu-entry/Title.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Title
|
||||
description: Returns the `title` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.Title]
|
||||
---
|
||||
|
||||
If you define the menu entry [automatically], the `Title` method returns the page’s [`LinkTitle`], falling back to its [`Title`].
|
||||
|
||||
If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `title` property, falling back to the page’s `LinkTitle`, then to its `Title`.
|
||||
|
||||
[`LinkTitle`]: /methods/page/linktitle
|
||||
[`Title`]: /methods/page/title
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ .Title }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
23
docs/content/en/methods/menu-entry/URL.md
Normal file
23
docs/content/en/methods/menu-entry/URL.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: URL
|
||||
description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [MENUENTRY.URL]
|
||||
---
|
||||
|
||||
For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property.
|
||||
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
[`RelPermalink`]: /methods/page/relpermalink
|
||||
31
docs/content/en/methods/menu-entry/Weight.md
Normal file
31
docs/content/en/methods/menu-entry/Weight.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Weight
|
||||
description: Returns the `weight` property of the given menu entry.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: int
|
||||
signatures: [MENUENTRY.Weight]
|
||||
---
|
||||
|
||||
If you define the menu entry [automatically], the `Weight` method returns the page’s [`Weight`].
|
||||
|
||||
If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page’s `Weight`.
|
||||
|
||||
[`Weight`]: /methods/page/weight
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
In this contrived example, we limit the number of menu entries based on weight:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
{{ if le .Weight 42 }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
13
docs/content/en/methods/menu-entry/_common/_index.md
Normal file
13
docs/content/en/methods/menu-entry/_common/_index.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
39
docs/content/en/methods/menu-entry/_common/pre-post.md
Normal file
39
docs/content/en/methods/menu-entry/_common/pre-post.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
In this site configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
enableEmoji = true
|
||||
|
||||
[[menus.main]]
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
post = ':point_left:'
|
||||
pre = ':point_right:'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
post = ':arrow_left:'
|
||||
pre = ':arrow_right:'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To render the menu:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li>
|
||||
{{ .Pre | markdownify }}
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ .Post | markdownify }}
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
[emoji shortcodes]: /quick-reference/emojis/
|
||||
12
docs/content/en/methods/menu-entry/_index.md
Normal file
12
docs/content/en/methods/menu-entry/_index.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Menu entry methods
|
||||
linkTitle: Menu entry
|
||||
description: Use these methods in your menu templates.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: methods
|
||||
---
|
||||
|
||||
Use these methods in your menu templates.
|
||||
65
docs/content/en/methods/menu/ByName.md
Normal file
65
docs/content/en/methods/menu/ByName.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: ByName
|
||||
description: Returns the given menu with its entries sorted by name.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: navigation.Menu
|
||||
signatures: [MENU.ByName]
|
||||
---
|
||||
|
||||
The `Sort` method returns the given menu with its entries sorted by `name`.
|
||||
|
||||
Consider this menu definition:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To sort the entries by `name`:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main.ByName }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/about/">About</a></li>
|
||||
<li><a href="/contact">Contact</a></li>
|
||||
<li><a href="/services/">Services</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
You can also sort menu entries using the [`sort`] function. For example, to sort by `name` in descending order:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range sort .Site.Menus.main "Name" "desc" }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
|
||||
|
||||
[`sort`]: /functions/collections/sort
|
||||
76
docs/content/en/methods/menu/ByWeight.md
Normal file
76
docs/content/en/methods/menu/ByWeight.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: ByWeight
|
||||
description: Returns the given menu with its entries sorted by weight, then by name, then by identifier.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: navigation.Menu
|
||||
signatures: [MENU.ByWeight]
|
||||
---
|
||||
|
||||
The `ByWeight` method returns the given menu with its entries sorted by [`weight`], then by `name`, then by `identifier`. This is the default sort order.
|
||||
|
||||
[`weight`]: /getting-started/glossary/#weight
|
||||
|
||||
Consider this menu definition:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
identifier = 'about'
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
identifier = 'services'
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
identifier = 'contact'
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To sort the entries by `weight`, then by `name`, then by `identifier`:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main.ByWeight }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/services/">Services</a></li>
|
||||
<li><a href="/about/">About</a></li>
|
||||
<li><a href="/contact">Contact</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
|
||||
|
||||
[details]: /content-management/menus/#properties-front-matter
|
||||
{{% /note %}}
|
||||
|
||||
You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range sort .Site.Menus.main "Weight" "desc" }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
|
||||
|
||||
[`sort`]: /functions/collections/sort
|
||||
50
docs/content/en/methods/menu/Limit.md
Normal file
50
docs/content/en/methods/menu/Limit.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Limit
|
||||
description: Returns the given menu, limited to the first N entries.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: navigation.Menu
|
||||
signatures: [MENU.Limit N]
|
||||
---
|
||||
|
||||
The `Limit` method returns the given menu, limited to the first N entries.
|
||||
|
||||
Consider this menu definition:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To sort the entries by name, and limit to the first 2 entries:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main.ByName.Limit 2 }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/about/">About</a></li>
|
||||
<li><a href="/contact">Contact</a></li>
|
||||
</ul>
|
||||
```
|
||||
51
docs/content/en/methods/menu/Reverse.md
Normal file
51
docs/content/en/methods/menu/Reverse.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Reverse
|
||||
description: Returns the given menu, reversing the sort order of its entries.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: navigation.Menu
|
||||
signatures: [MENU.Reverse]
|
||||
---
|
||||
|
||||
The `Reverse` method returns the given menu, reversing the sort order of its entries.
|
||||
|
||||
Consider this menu definition:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'About'
|
||||
pageRef = '/about'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Contact'
|
||||
pageRef = '/contact'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To sort the entries by name in descending order:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Menus.main.ByName.Reverse }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/services/">Services</a></li>
|
||||
<li><a href="/contact">Contact</a></li>
|
||||
<li><a href="/about/">About</a></li>
|
||||
</ul>
|
||||
```
|
||||
12
docs/content/en/methods/menu/_index.md
Normal file
12
docs/content/en/methods/menu/_index.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Menu methods
|
||||
linkTitle: Menu
|
||||
description: Use these methods when ranging through menu entries.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: methods
|
||||
---
|
||||
|
||||
Use these methods when ranging through menu entries.
|
||||
29
docs/content/en/methods/page/Aliases.md
Normal file
29
docs/content/en/methods/page/Aliases.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Aliases
|
||||
description: Returns the URL aliases as defined in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: '[]string'
|
||||
signatures: [PAGE.Aliases]
|
||||
---
|
||||
|
||||
The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter.
|
||||
|
||||
For example:
|
||||
|
||||
{{< code-toggle file=content/about.md fm=true >}}
|
||||
title = 'About'
|
||||
aliases = ['/old-url','/really-old-url']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To list the aliases:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Aliases }}
|
||||
{{ . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[aliases]: /content-management/urls/#aliases
|
||||
91
docs/content/en/methods/page/AllTranslations.md
Normal file
91
docs/content/en/methods/page/AllTranslations.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: AllTranslations
|
||||
description: Returns all translation of the given page, including the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Translations
|
||||
- methods/page/IsTranslated
|
||||
- methods/page/TranslationKey
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.AllTranslations]
|
||||
---
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 2
|
||||
|
||||
[languages.fr]
|
||||
contentDir = 'content/fr'
|
||||
languageCode = 'fr-FR'
|
||||
languageName = 'Français'
|
||||
weight = 3
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this content:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── de/
|
||||
│ ├── books/
|
||||
│ │ ├── book-1.md
|
||||
│ │ └── book-2.md
|
||||
│ └── _index.md
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── book-1.md
|
||||
│ │ └── book-2.md
|
||||
│ └── _index.md
|
||||
├── fr/
|
||||
│ ├── books/
|
||||
│ │ └── book-1.md
|
||||
│ └── _index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
And this template:
|
||||
|
||||
```go-html-template
|
||||
{{ with .AllTranslations }}
|
||||
<ul>
|
||||
{{ range . }}
|
||||
{{ $langName := or .Language.LanguageName .Language.Lang }}
|
||||
{{ $langCode := or .Language.LanguageCode .Language.Lang }}
|
||||
<li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo will render this list on the "Book 1" page of each site:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
|
||||
<li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
|
||||
<li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
On the "Book 2" page of the English and German sites, Hugo will render this:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
|
||||
<li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
|
||||
</ul>
|
||||
```
|
||||
43
docs/content/en/methods/page/AlternativeOutputFormats.md
Normal file
43
docs/content/en/methods/page/AlternativeOutputFormats.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: AlternativeOutputFormats
|
||||
description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/OutputFormats
|
||||
returnType: page.OutputFormats
|
||||
signatures: [PAGE.AlternativeOutputFormats]
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/output-format-definition.md" %}}
|
||||
|
||||
The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page.. See [details](/templates/output-formats/).
|
||||
|
||||
## Methods
|
||||
|
||||
{{% include "methods/page/_common/output-format-methods.md" %}}
|
||||
|
||||
## Example
|
||||
|
||||
Generate a `link` element in the `<head>` of each page for each of the alternative output formats:
|
||||
|
||||
```go-html-template
|
||||
<head>
|
||||
...
|
||||
{{ $title := printf "%s | %s" .Title site.Title }}
|
||||
{{ if .IsHome }}
|
||||
{{ $title = site.Title }}
|
||||
{{ end }}
|
||||
{{ range .AlternativeOutputFormats -}}
|
||||
{{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink $title | safeHTML }}
|
||||
{{ end }}
|
||||
...
|
||||
</head>
|
||||
```
|
||||
|
||||
On the site's home page, Hugo renders this to:
|
||||
|
||||
```html
|
||||
<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets, Inc.">
|
||||
```
|
||||
87
docs/content/en/methods/page/Ancestors.md
Normal file
87
docs/content/en/methods/page/Ancestors.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Ancestors
|
||||
description: Returns a collection of Page objects, one for each ancestor section of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/FirstSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.Ancestors]
|
||||
---
|
||||
|
||||
{{< new-in 0.109.0 >}}
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md <-- front matter: weight = 202311
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md <-- front matter: weight = 202312
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md <-- front matter: weight = 30
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md
|
||||
├── books/
|
||||
│ ├── _index.md <-- front matter: weight = 10
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md
|
||||
├── films/
|
||||
│ ├── _index.md <-- front matter: weight = 20
|
||||
│ ├── film-1.md
|
||||
│ └── film-2.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
And this template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Ancestors }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
On the November 2023 auctions page, Hugo renders:
|
||||
|
||||
```html
|
||||
<a href="/auctions/2023-11/">Auctions in November 2023</a>
|
||||
<a href="/auctions/">Auctions</a>
|
||||
<a href="/">Home</a>
|
||||
```
|
||||
|
||||
In the example above, notice that Hugo orders the ancestors from closest to furthest. This makes breadcrumb navigation simple:
|
||||
|
||||
```go-html-template
|
||||
<nav aria-label="breadcrumb" class="breadcrumb">
|
||||
<ol>
|
||||
{{ range .Ancestors.Reverse }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
<li class="active">
|
||||
<a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
</li>
|
||||
</ol>
|
||||
</nav>
|
||||
```
|
||||
|
||||
With some CSS, the code above renders something like this, where each breadcrumb links to its page:
|
||||
|
||||
```text
|
||||
Home > Auctions > Auctions in November 2023 > Auction 1
|
||||
```
|
||||
37
docs/content/en/methods/page/BundleType.md
Normal file
37
docs/content/en/methods/page/BundleType.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: BundleType
|
||||
description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: files.ContentClass
|
||||
signatures: [PAGE.BundleType]
|
||||
---
|
||||
|
||||
A page bundle is a directory that encapsulates both content and associated [resources]. There are two types of page bundles: [leaf bundles] and [branch bundles]. See [details](/content-management/page-bundles/).
|
||||
|
||||
The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── films/
|
||||
│ ├── film-1/
|
||||
│ │ ├── a.jpg
|
||||
│ │ └── index.md <-- leaf bundle
|
||||
│ ├── _index.md <-- branch bundle
|
||||
│ ├── b.jpg
|
||||
│ ├── film-2.md
|
||||
│ └── film-3.md
|
||||
└── _index.md <-- branch bundle
|
||||
```
|
||||
|
||||
To get the value within a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .BundleType }}
|
||||
```
|
||||
|
||||
[resources]: /getting-started/glossary/#resource
|
||||
[leaf bundles]: /getting-started/glossary/#leaf-bundle
|
||||
[branch bundles]: /getting-started/glossary/#branch-bundle
|
||||
66
docs/content/en/methods/page/CodeOwners.md
Normal file
66
docs/content/en/methods/page/CodeOwners.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: CodeOwners
|
||||
description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/GitInfo
|
||||
returnType: '[]string'
|
||||
signatures: [PAGE.CodeOwners]
|
||||
---
|
||||
|
||||
GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more:
|
||||
|
||||
- [GitHub CODEOWNERS documentation]
|
||||
- [GitLab CODEOWNERS documentation]
|
||||
|
||||
Use the `CodeOwners` method on a `Page` object to determine the code owners for the given page.
|
||||
|
||||
[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
|
||||
[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html
|
||||
|
||||
To use the `CodeOwners` method you must enable access to your local Git repository:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
enableGitInfo = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Consider this project structure:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
├── content/
|
||||
│ ├── books/
|
||||
│ │ └── les-miserables.md
|
||||
│ └── films/
|
||||
│ └── the-hunchback-of-notre-dame.md
|
||||
└── CODEOWNERS
|
||||
```
|
||||
|
||||
And this CODEOWNERS file:
|
||||
|
||||
```text
|
||||
* @jdoe
|
||||
/content/books/ @tjones
|
||||
/content/films/ @mrichards @rsmith
|
||||
```
|
||||
|
||||
The table below shows the slice of code owners returned for each file:
|
||||
|
||||
Path|Code owners
|
||||
:--|:--
|
||||
`books/les-miserables.md`|`[@tjones]`
|
||||
`films/the-hunchback-of-notre-dame.md`|`[@mrichards @rsmith]`
|
||||
|
||||
Render the code owners for each content page:
|
||||
|
||||
```go-html-template
|
||||
{{ range .CodeOwners }}
|
||||
{{ . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
|
||||
|
||||
[`resources.GetRemote`]: functions/resources/getremote
|
||||
22
docs/content/en/methods/page/Content.md
Normal file
22
docs/content/en/methods/page/Content.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Content
|
||||
description: Returns the rendered content of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/RawContent
|
||||
- methods/page/Plain
|
||||
- methods/page/PlainWords
|
||||
- methods/page/RenderShortcodes
|
||||
returnType: template.HTML
|
||||
signatures: [PAGE.Content]
|
||||
---
|
||||
|
||||
The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter.
|
||||
|
||||
[shortcodes]: /getting-started/glossary/#shortcode
|
||||
|
||||
```go-html-template
|
||||
{{ .Content }}
|
||||
```
|
||||
60
docs/content/en/methods/page/CurrentSection.md
Normal file
60
docs/content/en/methods/page/CurrentSection.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: CurrentSection
|
||||
description: Returns the Page object of the section in which the given page resides.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/FirstSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.CurrentSection]
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
{{% note %}}
|
||||
The current section of a [section] page, [taxonomy] page, [term] page, or the home page, is itself.
|
||||
|
||||
[section]: /getting-started/glossary/#section
|
||||
[taxonomy]: /getting-started/glossary/#taxonomy
|
||||
[term]: /getting-started/glossary/#term
|
||||
{{% /note %}}
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md <-- current section: 2023-11
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md <-- current section: 2023-11
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md <-- current section: auctions
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md <-- current section: auctions
|
||||
├── books/
|
||||
│ ├── _index.md <-- current section: books
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md <-- current section: books
|
||||
├── films/
|
||||
│ ├── _index.md <-- current section: films
|
||||
│ ├── film-1.md
|
||||
│ └── film-2.md <-- current section: films
|
||||
└── _index.md <-- current section: home
|
||||
```
|
||||
|
||||
To create a link to the current section page:
|
||||
|
||||
```go-html-template
|
||||
<a href="{{ .CurrentSection.RelPermalink }}">{{ .CurrentSection.LinkTitle }}</a>
|
||||
```
|
||||
111
docs/content/en/methods/page/Data.md
Normal file
111
docs/content/en/methods/page/Data.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: Data
|
||||
description: Returns a unique data object for each page kind.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: page.Data
|
||||
signatures: [PAGE.Data]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The `Data` method on a `Page` object returns a unique data object for each [page kind].
|
||||
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
|
||||
{{% note %}}
|
||||
The `Data` method is only useful within [taxonomy] and [term] templates.
|
||||
|
||||
Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
|
||||
|
||||
[`Pages`]: /methods/page/pages/
|
||||
[`RegularPages`]: /methods/page/regularpages/
|
||||
[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
|
||||
[term]: /getting-started/glossary/#term
|
||||
[taxonomy]: /getting-started/glossary/#taxonomy
|
||||
{{% /note %}}
|
||||
|
||||
The examples that follow are based on 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
|
||||
```
|
||||
|
||||
## In a taxonomy template
|
||||
|
||||
Use these methods on the `Data` object within a taxonomy template.
|
||||
|
||||
Singular
|
||||
: (`string`) Returns the singular name of the taxonomy.
|
||||
|
||||
```go-html-template
|
||||
{{ .Data.Singular }} → genre
|
||||
```
|
||||
|
||||
Plural
|
||||
: (`string`) Returns the plural name of the taxonomy.
|
||||
|
||||
```go-html-template
|
||||
{{ .Data.Plural }} → genres
|
||||
```
|
||||
|
||||
Terms
|
||||
: (`page.Taxonomy`) Returns the taxonomy object, consisting of a map of terms and the [weighted pages] associated with each term.
|
||||
|
||||
```go-html-template
|
||||
{{ $taxonomyObject := .Data.Terms }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Once you have captured the taxonomy object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
|
||||
|
||||
[taxonomy methods]: /methods/taxonomy
|
||||
{{% /note %}}
|
||||
|
||||
Learn more about [taxonomy templates].
|
||||
|
||||
## In a term template
|
||||
|
||||
Use these methods on the `Data` object within a term template.
|
||||
|
||||
Singular
|
||||
: (`string`) Returns the singular name of the taxonomy.
|
||||
|
||||
```go-html-template
|
||||
{{ .Data.Singular }} → genre
|
||||
```
|
||||
|
||||
Plural
|
||||
: (`string`) Returns the plural name of the taxonomy.
|
||||
|
||||
```go-html-template
|
||||
{{ .Data.Plural }} → genres
|
||||
```
|
||||
|
||||
Term
|
||||
: (`string`) Returns the name of the term.
|
||||
|
||||
```go-html-template
|
||||
{{ .Data.Term }} → suspense
|
||||
```
|
||||
|
||||
Learn more about [term templates].
|
||||
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[term templates]: /templates/taxonomy-templates/
|
||||
[weighted pages]: /getting-started/glossary/#weighted-page
|
||||
39
docs/content/en/methods/page/Date.md
Normal file
39
docs/content/en/methods/page/Date.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Date
|
||||
description: Returns the date of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/ExpiryDate
|
||||
- methods/page/LastMod
|
||||
- methods/page/PublishDate
|
||||
returnType: time.Time
|
||||
signatures: [PAGE.Date]
|
||||
---
|
||||
|
||||
Set the date in front matter:
|
||||
|
||||
{{< code-toggle file=content/news/article-1.md fm=true >}}
|
||||
title = 'Article 1'
|
||||
date = 2023-10-19T00:40:04-07:00
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% note %}}
|
||||
The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details].
|
||||
|
||||
[details]: /getting-started/configuration/#configure-dates
|
||||
{{% /note %}}
|
||||
|
||||
The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
|
||||
|
||||
```go-html-template
|
||||
{{ .Date | time.Format ":date_medium" }} → Oct 19, 2023
|
||||
```
|
||||
|
||||
In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details].
|
||||
|
||||
[`time.Format`]: /functions/time/format
|
||||
[details]: /getting-started/configuration/#configure-dates
|
||||
[time methods]: /methods/time
|
||||
[time.Time]: https://pkg.go.dev/time#Time
|
||||
28
docs/content/en/methods/page/Description.md
Normal file
28
docs/content/en/methods/page/Description.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Description
|
||||
description: Returns the description of the given page as defined in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Summary
|
||||
returnType: string
|
||||
signatures: [PAGE.Description]
|
||||
---
|
||||
|
||||
Conceptually different that a [content summary], a page description is typically used in metadata about the page.
|
||||
|
||||
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
|
||||
title = 'How to make spicy tuna hand rolls'
|
||||
description = 'Instructions for making spicy tuna hand rolls.'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code file=layouts/baseof.html >}}
|
||||
<head>
|
||||
...
|
||||
<meta name="description" content="{{ .Description }}">
|
||||
...
|
||||
</head>
|
||||
{{< /code >}}
|
||||
|
||||
[content summary]: /content-management/summaries
|
||||
21
docs/content/en/methods/page/Draft.md
Normal file
21
docs/content/en/methods/page/Draft.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Draft
|
||||
description: Reports whether the given page is a draft as defined in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: bool
|
||||
signatures: [PAGE.Draft]
|
||||
---
|
||||
|
||||
By default, Hugo does not publish draft pages when you build your site. To include draft pages when you build your site, use the `--buildDrafts` command line flag.
|
||||
|
||||
{{< code-toggle file=content/posts/post-1.md fm=true >}}
|
||||
title = 'Post 1'
|
||||
draft = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{ .Draft }} → true
|
||||
```
|
||||
21
docs/content/en/methods/page/Eq.md
Normal file
21
docs/content/en/methods/page/Eq.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Eq
|
||||
description: Reports whether two Page objects are equal.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: bool
|
||||
signatures: [PAGE1.Eq PAGE2]
|
||||
---
|
||||
|
||||
In this contrived example from a single page template, we list all pages in the current section except for the current page.
|
||||
|
||||
```go-html-template
|
||||
{{ $currentPage := . }}
|
||||
{{ range .CurrentSection.Pages }}
|
||||
{{ if not (.Eq $currentPage) }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
35
docs/content/en/methods/page/ExpiryDate.md
Normal file
35
docs/content/en/methods/page/ExpiryDate.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: ExpiryDate
|
||||
description: Returns the expiry date of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Date
|
||||
- methods/page/LastMod
|
||||
- methods/page/PublishDate
|
||||
returnType: time.Time
|
||||
signatures: [PAGE.ExpiryDate]
|
||||
---
|
||||
|
||||
By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag.
|
||||
|
||||
Set the expiry date in front matter:
|
||||
|
||||
{{< code-toggle file=content/news/article-1.md fm=true >}}
|
||||
title = 'Article 1'
|
||||
expiryDate = 2024-10-19T00:32:13-07:00
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The expiry date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
|
||||
|
||||
```go-html-template
|
||||
{{ .ExpiryDate | time.Format ":date_medium" }} → Oct 19, 2024
|
||||
```
|
||||
|
||||
In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details].
|
||||
|
||||
[`time.Format`]: /functions/time/format
|
||||
[details]: /getting-started/configuration/#configure-dates
|
||||
[time methods]: /methods/time
|
||||
[time.Time]: https://pkg.go.dev/time#Time
|
||||
190
docs/content/en/methods/page/File.md
Normal file
190
docs/content/en/methods/page/File.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
title: File
|
||||
description: For pages backed by a file, returns file information for the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: hugolib.fileInfo
|
||||
signatures: [PAGE.File]
|
||||
toc: true
|
||||
---
|
||||
|
||||
By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist.
|
||||
|
||||
To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example:
|
||||
|
||||
```text
|
||||
content/
|
||||
└── books/
|
||||
├── _index.md <-- the top level section page
|
||||
├── book-1.md
|
||||
└── book-2.md
|
||||
```
|
||||
|
||||
Code defensively by verifying file existence as shown in each of the examples below.
|
||||
|
||||
## Methods
|
||||
|
||||
{{% note %}}
|
||||
The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
|
||||
{{% /note %}}
|
||||
|
||||
###### BaseFileName
|
||||
|
||||
(`string`) The file name, excluding the extension.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .BaseFileName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### ContentBaseName
|
||||
|
||||
(`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .ContentBaseName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Dir
|
||||
|
||||
(`string`) The file path, excluding the file name, relative to the `content` directory.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .Dir }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Ext
|
||||
|
||||
(`string`) The file extension.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .Ext }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Filename
|
||||
|
||||
(`string`) The absolute file path.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .Filename }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Lang
|
||||
|
||||
(`string`) The language associated with the given file.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .Lang }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### LogicalName
|
||||
|
||||
(`string`) The file name.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .LogicalName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Path
|
||||
|
||||
(`string`) The file path, relative to the `content` directory.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .Path }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### TranslationBaseName
|
||||
|
||||
(`string`) The file name, excluding the extension and language identifier.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .TranslationBaseName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### UniqueID
|
||||
|
||||
(`string`) The MD5 hash of `.File.Path`.
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .UniqueID }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Consider this content structure in a multilingual project:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── news/
|
||||
│ ├── b/
|
||||
│ │ ├── index.de.md <-- leaf bundle
|
||||
│ │ └── index.en.md <-- leaf bundle
|
||||
│ ├── a.de.md <-- regular content
|
||||
│ ├── a.en.md <-- regular content
|
||||
│ ├── _index.de.md <-- branch bundle
|
||||
│ └── _index.en.md <-- branch bundle
|
||||
├── _index.de.md
|
||||
└── _index.en.md
|
||||
```
|
||||
|
||||
With the English language site:
|
||||
|
||||
|regular content|leaf bundle|branch bundle
|
||||
:--|:--|:--|:--
|
||||
BaseFileName|a.en|index.en|_index.en
|
||||
ContentBaseName|a|b|news
|
||||
Dir|news/|news/b/|news/
|
||||
Ext|md|md|md
|
||||
Filename|/home/user/...|/home/user/...|/home/user/...
|
||||
Lang|en|en|en
|
||||
LogicalName|a.en.md|index.en.md|_index.en.md
|
||||
Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
|
||||
TranslationBaseName|a|index|_index
|
||||
UniqueID|15be14b...|186868f...|7d9159d...
|
||||
|
||||
## Defensive coding
|
||||
|
||||
Some of the pages on a site may not be backed by a file. For example:
|
||||
|
||||
- Top level section pages
|
||||
- Taxonomy pages
|
||||
- Term pages
|
||||
|
||||
Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example:
|
||||
|
||||
```text
|
||||
WARN .File.ContentBaseName on zero object. Wrap it in if or with...
|
||||
```
|
||||
|
||||
To code defensively, first check for file existence:
|
||||
|
||||
```go-html-template
|
||||
{{ with .File }}
|
||||
{{ .ContentBaseName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[section]: /getting-started/glossary/#section
|
||||
[taxonomy]: /getting-started/glossary/#taxonomy
|
||||
[term]: /getting-started/glossary/#term
|
||||
56
docs/content/en/methods/page/FirstSection.md
Normal file
56
docs/content/en/methods/page/FirstSection.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: FirstSection
|
||||
description: Returns the Page object of the top level section of which the given page is a descendant.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.FirstSection]
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
{{% note %}}
|
||||
When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself.
|
||||
{{% /note %}}
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md <-- first section: auctions
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md <-- first section: auctions
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md <-- first section: auctions
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md <-- first section: auctions
|
||||
├── books/
|
||||
│ ├── _index.md <-- first section: books
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md <-- first section: books
|
||||
├── films/
|
||||
│ ├── _index.md <-- first section: films
|
||||
│ ├── film-1.md
|
||||
│ └── film-2.md <-- first section: films
|
||||
└── _index.md <-- first section: home
|
||||
```
|
||||
|
||||
To link to the top level section of which the current page is a descendant:
|
||||
|
||||
```go-html-template
|
||||
<a href="{{ .FirstSection.RelPermalink }}">{{ .FirstSection.LinkTitle }}</a>
|
||||
```
|
||||
106
docs/content/en/methods/page/Fragments.md
Normal file
106
docs/content/en/methods/page/Fragments.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Fragments
|
||||
description: Returns a data structure of the fragments in the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/TableOfContents
|
||||
returnType: tableofcontents.Fragments
|
||||
signatures: [PAGE.Fragments]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.111.0 >}}
|
||||
|
||||
In a URL, whether absolute or relative, the [fragment] links to an `id` attribute of an HTML element on the page.
|
||||
|
||||
```text
|
||||
/articles/article-1#section-2
|
||||
------------------- ---------
|
||||
path fragment
|
||||
```
|
||||
|
||||
Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
|
||||
|
||||
Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure.
|
||||
|
||||
## Methods
|
||||
|
||||
Headings
|
||||
: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre>
|
||||
```
|
||||
|
||||
HeadingsMap
|
||||
: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre>
|
||||
```
|
||||
|
||||
Identifiers
|
||||
: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure:
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre>
|
||||
```
|
||||
|
||||
Identifiers.Contains ID
|
||||
: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook].
|
||||
|
||||
```go-html-template
|
||||
{{ .Fragments.Identifiers.Contains "section-2" }} → true
|
||||
```
|
||||
|
||||
Identifiers.Count ID
|
||||
: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
|
||||
|
||||
```go-html-template
|
||||
{{ .Fragments.Identifiers.Count "section-2" }} → 1
|
||||
```
|
||||
|
||||
ToHTML
|
||||
: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
|
||||
|
||||
Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration.
|
||||
|
||||
```go-html-template
|
||||
{{ $startLevel := 2 }}
|
||||
{{ $endLevel := 3 }}
|
||||
{{ $ordered := true }}
|
||||
{{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<nav id="TableOfContents">
|
||||
<ol>
|
||||
<li><a href="#section-1">Section 1</a>
|
||||
<ol>
|
||||
<li><a href="#section-11">Section 1.1</a></li>
|
||||
<li><a href="#section-12">Section 1.2</a></li>
|
||||
</ol>
|
||||
</li>
|
||||
<li><a href="#section-2">Section 2</a></li>
|
||||
</ol>
|
||||
</nav>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
It is safe to use the `Fragments` methods within a render hook, even for the current page.
|
||||
|
||||
When using the `Fragments` methods within a shortcode, call the shortcode using the `{{</* */>}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
|
||||
{{% /note %}}
|
||||
|
||||
[atx]: https://spec.commonmark.org/0.30/#atx-headings
|
||||
[fragment]: /getting-started/glossary/#fragment
|
||||
[markdown attribute]: /getting-started/glossary/#markdown-attribute
|
||||
[setext]: https://spec.commonmark.org/0.30/#setext-headings
|
||||
[table of contents]: /methods/page/tableofcontents
|
||||
[walking]: /getting-started/glossary/#walk
|
||||
[`tableofcontents`]: /methods/page/tableofcontents
|
||||
[render hook]: /getting-started/glossary/#render-hook
|
||||
20
docs/content/en/methods/page/FuzzyWordCount.md
Normal file
20
docs/content/en/methods/page/FuzzyWordCount.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: FuzzyWordCount
|
||||
description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/WordCount
|
||||
- methods/page/ReadingTime
|
||||
returnType: int
|
||||
signatures: [PAGE.FuzzyWordCount]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ .FuzzyWordCount }} → 200
|
||||
```
|
||||
|
||||
To get the exact word count, use the [`WordCount`] method.
|
||||
|
||||
[`WordCount`]: /methods/page/wordcount
|
||||
65
docs/content/en/methods/page/GetPage.md
Normal file
65
docs/content/en/methods/page/GetPage.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: GetPage
|
||||
description: Returns a Page object from the given path.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/site/GetPage
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.GetPage PATH]
|
||||
aliases: [/functions/getpage]
|
||||
---
|
||||
|
||||
The `GetPage` method is also available on a `Site` object. See [details].
|
||||
|
||||
[details]: /methods/site/getpage
|
||||
|
||||
When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory.
|
||||
|
||||
If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build.
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── works/
|
||||
│ ├── paintings/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── starry-night.md
|
||||
│ │ └── the-mona-lisa.md
|
||||
│ ├── sculptures/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── david.md
|
||||
│ │ └── the-thinker.md
|
||||
│ └── _index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template:
|
||||
|
||||
```go-html-template
|
||||
{{ with .GetPage "starry-night" }}
|
||||
{{ .Title }} → Starry Night
|
||||
{{ end }}
|
||||
|
||||
{{ with .GetPage "./starry-night" }}
|
||||
{{ .Title }} → Starry Night
|
||||
{{ end }}
|
||||
|
||||
{{ with .GetPage "../paintings/starry-night" }}
|
||||
{{ .Title }} → Starry Night
|
||||
{{ end }}
|
||||
|
||||
{{ with .GetPage "/works/paintings/starry-night" }}
|
||||
{{ .Title }} → Starry Night
|
||||
{{ end }}
|
||||
|
||||
{{ with .GetPage "../sculptures/david" }}
|
||||
{{ .Title }} → David
|
||||
{{ end }}
|
||||
|
||||
{{ with .GetPage "/works/sculptures/david" }}
|
||||
{{ .Title }} → David
|
||||
{{ end }}
|
||||
```
|
||||
41
docs/content/en/methods/page/GetTerms.md
Normal file
41
docs/content/en/methods/page/GetTerms.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: GetTerms
|
||||
description: Returns a collection of term pages for terms defined on the given page in the given taxonomy, ordered according to the sequence in which they appear in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.GetTerms TAXONOMY]
|
||||
---
|
||||
|
||||
Given this front matter:
|
||||
|
||||
{{< code-toggle file=content/books/les-miserables.md fm=true >}}
|
||||
title = 'Les Misérables'
|
||||
tags = ['historical','classic','fiction']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ with .GetTerms "tags" }}
|
||||
<p>Tags</p>
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>Tags</p>
|
||||
<ul>
|
||||
<li><a href="/tags/historical/">historical</a></li>
|
||||
<li><a href="/tags/classic/">classic</a></li>
|
||||
<li><a href="/tags/fiction/">fiction</a></li>
|
||||
</ul>
|
||||
```
|
||||
146
docs/content/en/methods/page/GitInfo.md
Normal file
146
docs/content/en/methods/page/GitInfo.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: GitInfo
|
||||
description: Returns Git information related to the last commit of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/CodeOwners
|
||||
returnType: source.GitInfo
|
||||
signatures: [PAGE.GitInfo]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The `GitInfo` method on a `Page` object returns an object with additional methods.
|
||||
|
||||
{{% note %}}
|
||||
Hugo's Git integration is performant, but may increase build times on large sites.
|
||||
{{% /note %}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install [Git], create a repository, and commit your project files.
|
||||
|
||||
You must also allow Hugo to access your repository. In your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
enableGitInfo = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Alternatively, use the command line flag when building your site:
|
||||
|
||||
```sh
|
||||
hugo --enableGitInfo
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file.
|
||||
|
||||
This is configurable. See [details].
|
||||
|
||||
[details]: /getting-started/configuration/#configure-dates
|
||||
{{% /note %}}
|
||||
|
||||
## Methods
|
||||
|
||||
###### AbbreviatedHash
|
||||
|
||||
(`string`) The abbreviated commit hash.
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .AbbreviatedHash }} → aab9ec0b3
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### AuthorDate
|
||||
|
||||
(`time.Time`) The author date.
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### AuthorEmail
|
||||
|
||||
(`string`) The author's email address, respecting [gitmailmap].
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .AuthorEmail }} → jsmith@example.org
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### AuthorName
|
||||
|
||||
(`string`) The author's name, respecting [gitmailmap].
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .AuthorName }} → John Smith
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### CommitDate
|
||||
|
||||
(`time.Time`) The commit date.
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Hash
|
||||
|
||||
(`string`) The commit hash.
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
###### Subject
|
||||
|
||||
(`string`) The commit message subject.
|
||||
|
||||
```go-html-template
|
||||
{{ with .GitInfo }}
|
||||
{{ .Subject }} → Add tutorials
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Last modified date
|
||||
|
||||
By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
|
||||
|
||||
You can change this behavior in your [site configuration].
|
||||
|
||||
[git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[gitmailmap]: https://git-scm.com/docs/gitmailmap
|
||||
[site configuration]: /getting-started/configuration/#configure-front-matter
|
||||
|
||||
## Hosting considerations
|
||||
|
||||
When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file.
|
||||
|
||||
Some providers perform deep clones by default, others allow you to configure the clone depth, and some providers only perform shallow clones.
|
||||
|
||||
Hosting service | Default clone depth | Configurable
|
||||
:-- | :-- | :--
|
||||
Cloudflare Pages | Shallow | Yes [^CFP]
|
||||
DigitalOcean App Platform | Deep | N/A
|
||||
GitHub Pages | Shallow | Yes [^GHP]
|
||||
GitLab Pages | Shallow | Yes [^GLP]
|
||||
Netlify | Deep | N/A
|
||||
Render | Shallow | No
|
||||
Vercel | Shallow | No
|
||||
|
||||
[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`).
|
||||
|
||||
[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure).
|
||||
|
||||
[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd).
|
||||
31
docs/content/en/methods/page/HasMenuCurrent.md
Normal file
31
docs/content/en/methods/page/HasMenuCurrent.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: HasMenuCurrent
|
||||
description: Reports whether the given page object matches the page object associated with one of the child menu entries under the given menu entry in the given menu.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsMenuCurrent
|
||||
returnType: bool
|
||||
signatures: [PAGE.HasMenuCurrent MENU MENUENTRY]
|
||||
aliases: [/functions/hasmenucurrent]
|
||||
---
|
||||
|
||||
If the page object associated with the menu entry is a section, this method also returns `true` for any descendant of that section.
|
||||
|
||||
```go-html-template
|
||||
{{ $currentPage := . }}
|
||||
{{ range site.Menus.main }}
|
||||
{{ if $currentPage.IsMenuCurrent .Menu . }}
|
||||
<a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ else if $currentPage.HasMenuCurrent .Menu . }}
|
||||
<a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ else }}
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
See [menu templates] for a complete example.
|
||||
|
||||
[menu templates]: /templates/menu-templates/#example
|
||||
50
docs/content/en/methods/page/HasShortcode.md
Normal file
50
docs/content/en/methods/page/HasShortcode.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: HasShortcode
|
||||
description: Reports whether the given shortcode is called by the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: bool
|
||||
signatures: [PAGE.HasShortcode NAME]
|
||||
---
|
||||
|
||||
By example, let's use [Plotly] to render a chart:
|
||||
|
||||
[Plotly]: https://plotly.com/javascript/
|
||||
|
||||
{{< code file=contents/example.md lang=markdown >}}
|
||||
{{</* plotly */>}}
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"x": ["giraffes", "orangutans", "monkeys"],
|
||||
"y": [20, 14, 23],
|
||||
"type": "bar"
|
||||
}
|
||||
],
|
||||
}
|
||||
{{</* /plotly */>}}
|
||||
{{< /code >}}
|
||||
|
||||
The shortcode is simple:
|
||||
|
||||
{{< code file=layouts/shortcodes/plotly.html >}}
|
||||
{{ $id := printf "plotly-%02d" .Ordinal }}
|
||||
<div id="{{ $id }}"></div>
|
||||
<script>
|
||||
Plotly.newPlot(document.getElementById({{ $id }}), {{ .Inner | safeJS }});
|
||||
</script>
|
||||
{{< /code >}}
|
||||
|
||||
Now we can selectively load the required JavaScript on pages that call the "plotly" shortcode:
|
||||
|
||||
{{< code file=layouts/baseof.html >}}
|
||||
<head>
|
||||
...
|
||||
{{ if .HasShortcode "plotly" }}
|
||||
<script src="https://cdn.plot.ly/plotly-2.28.0.min.js"></script>
|
||||
{{ end }}
|
||||
...
|
||||
</head>
|
||||
{{< /code >}}
|
||||
18
docs/content/en/methods/page/HeadingsFiltered.md
Normal file
18
docs/content/en/methods/page/HeadingsFiltered.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: HeadingsFiltered
|
||||
description: Returns a slice of headings for each page related to the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/pages/Related
|
||||
- methods/page/Fragments
|
||||
returnType: tableofcontents.Headings
|
||||
signatures: [PAGE.HeadingsFiltered]
|
||||
---
|
||||
|
||||
Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
|
||||
|
||||
[`Pages`]: /methods/pages/
|
||||
[`Related`]: /methods/pages/related
|
||||
[details]: /content-management/related/#index-content-headings-in-related-content
|
||||
102
docs/content/en/methods/page/InSection.md
Normal file
102
docs/content/en/methods/page/InSection.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: InSection
|
||||
description: Reports whether the given page is in the given section.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/FirstSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: bool
|
||||
signatures: [PAGE.InSection SECTION]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The `InSection` method on a page object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling.
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When rendering the "auction-1" page:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/" }}
|
||||
{{ $.InSection . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.InSection . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11" }}
|
||||
{{ $.InSection . }} → true
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
|
||||
{{ $.InSection . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
|
||||
|
||||
```go-html-template
|
||||
{{ $path := "/auctions/2023-11" }}
|
||||
{{ with .Site.GetPage $path }}
|
||||
{{ $.InSection . }} → true
|
||||
{{ else }}
|
||||
{{ errorf "Unable to find the section with path %s" $path }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Understanding context
|
||||
|
||||
Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ .InSection . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
|
||||
|
||||
{{% note %}}
|
||||
Use the `$` to get the context passed into the template.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.InSection . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
[`with`]: /functions/go-template/with
|
||||
[`else`]: /functions/go-template/else
|
||||
100
docs/content/en/methods/page/IsAncestor.md
Normal file
100
docs/content/en/methods/page/IsAncestor.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: IsAncestor
|
||||
description: Reports whether PAGE1 in an ancestor of PAGE2.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/FirstSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: bool
|
||||
signatures: [PAGE1.IsAncestor PAGE2]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When rendering the "auctions" page:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/" }}
|
||||
{{ $.IsAncestor . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.IsAncestor . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11" }}
|
||||
{{ $.IsAncestor . }} → true
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
|
||||
{{ $.IsAncestor . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
|
||||
|
||||
```go-html-template
|
||||
{{ $path := "/auctions/2023-11" }}
|
||||
{{ with .Site.GetPage $path }}
|
||||
{{ $.IsAncestor . }} → true
|
||||
{{ else }}
|
||||
{{ errorf "Unable to find the section with path %s" $path }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Understanding context
|
||||
|
||||
Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ .IsAncestor . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
|
||||
|
||||
{{% note %}}
|
||||
Use the `$` to get the context passed into the template.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.IsAncestor . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
[`with`]: /functions/go-template/with
|
||||
[`else`]: /functions/go-template/else
|
||||
99
docs/content/en/methods/page/IsDescendant.md
Normal file
99
docs/content/en/methods/page/IsDescendant.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: IsDescendant
|
||||
description: Reports whether PAGE1 in a descendant of PAGE2.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/FirstSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/Parent
|
||||
- methods/page/Sections
|
||||
returnType: bool
|
||||
signatures: [PAGE1.IsDescendant PAGE2]
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When rendering the "auctions" page:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/" }}
|
||||
{{ $.IsDescendant . }} → true
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.IsDescendant . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11" }}
|
||||
{{ $.IsDescendant . }} → false
|
||||
{{ end }}
|
||||
|
||||
{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
|
||||
{{ $.IsDescendant . }} → false
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
|
||||
|
||||
```go-html-template
|
||||
{{ $path := "/auctions/2023-11" }}
|
||||
{{ with .Site.GetPage $path }}
|
||||
{{ $.IsDescendant . }} → true
|
||||
{{ else }}
|
||||
{{ errorf "Unable to find the section with path %s" $path }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Understanding context
|
||||
|
||||
Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ .IsDescendant . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
|
||||
|
||||
{{% note %}}
|
||||
Use the `$` to get the context passed into the template.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Site.GetPage "/auctions" }}
|
||||
{{ $.IsDescendant . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
[`with`]: /functions/go-template/with
|
||||
[`else`]: /functions/go-template/else
|
||||
31
docs/content/en/methods/page/IsHome.md
Normal file
31
docs/content/en/methods/page/IsHome.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: IsHome
|
||||
description: Reports whether the given page is the home page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsNode
|
||||
- methods/page/IsPage
|
||||
- methods/page/IsSection
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsHome]
|
||||
---
|
||||
|
||||
The `IsHome` method on a `Page` object returns `true` if the [page kind] is `home`.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.md <-- kind = page
|
||||
│ ├── book-2.md <-- kind = page
|
||||
│ └── _index.md <-- kind = section
|
||||
└── _index.md <-- kind = home
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .IsHome }}
|
||||
```
|
||||
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
29
docs/content/en/methods/page/IsMenuCurrent.md
Normal file
29
docs/content/en/methods/page/IsMenuCurrent.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: IsMenuCurrent
|
||||
description: Reports whether the given page object matches the page object associated with the given menu entry in the given menu.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/HasMenuCurrent
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsMenuCurrent MENU MENUENTRY]
|
||||
aliases: [/functions/ismenucurrent]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $currentPage := . }}
|
||||
{{ range site.Menus.main }}
|
||||
{{ if $currentPage.IsMenuCurrent .Menu . }}
|
||||
<a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ else if $currentPage.HasMenuCurrent .Menu . }}
|
||||
<a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ else }}
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
See [menu templates] for a complete example.
|
||||
|
||||
[menu templates]: /templates/menu-templates/#example
|
||||
36
docs/content/en/methods/page/IsNode.md
Normal file
36
docs/content/en/methods/page/IsNode.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: IsNode
|
||||
description: Reports whether the given page is a node.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsHome
|
||||
- methods/page/IsPage
|
||||
- methods/page/IsSection
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsNode]
|
||||
---
|
||||
|
||||
The `IsNode` method on a `Page` object returns `true` if the [page kind] is `home`, `section`, `taxonomy`, or `term`.
|
||||
|
||||
It returns `false` is the page kind is `page`.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.md <-- kind = page, node = false
|
||||
│ ├── book-2.md <-- kind = page, node = false
|
||||
│ └── _index.md <-- kind = section, node = true
|
||||
├── tags/
|
||||
│ ├── fiction/
|
||||
│ │ └── _index.md <-- kind = term, node = true
|
||||
│ └── _index.md <-- kind = taxonomy, node = true
|
||||
└── _index.md <-- kind = home, node = true
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .IsNode }}
|
||||
```
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
31
docs/content/en/methods/page/IsPage.md
Normal file
31
docs/content/en/methods/page/IsPage.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: IsPage
|
||||
description: Reports whether the given page is a regular page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsHome
|
||||
- methods/page/IsNode
|
||||
- methods/page/IsSection
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsPage]
|
||||
---
|
||||
|
||||
The `IsPage` method on a `Page` object returns `true` if the [page kind] is `page`.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.md <-- kind = page
|
||||
│ ├── book-2.md <-- kind = page
|
||||
│ └── _index.md <-- kind = section
|
||||
└── _index.md <-- kind = home
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .IsPage }}
|
||||
```
|
||||
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
31
docs/content/en/methods/page/IsSection.md
Normal file
31
docs/content/en/methods/page/IsSection.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: IsSection
|
||||
description: Reports whether the given page is a section page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/IsHome
|
||||
- methods/page/IsNode
|
||||
- methods/page/IsPage
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsSection]
|
||||
---
|
||||
|
||||
The `IsSection` method on a `Page` object returns `true` if the [page kind] is `section`.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.md <-- kind = page
|
||||
│ ├── book-2.md <-- kind = page
|
||||
│ └── _index.md <-- kind = section
|
||||
└── _index.md <-- kind = home
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .IsSection }}
|
||||
```
|
||||
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
59
docs/content/en/methods/page/IsTranslated.md
Normal file
59
docs/content/en/methods/page/IsTranslated.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: IsTranslated
|
||||
description: Reports whether the given page has one or more translations.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Translations
|
||||
- methods/page/AllTranslations
|
||||
- methods/page/TranslationKey
|
||||
returnType: bool
|
||||
signatures: [PAGE.IsTranslated]
|
||||
---
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this content:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── de/
|
||||
│ ├── books/
|
||||
│ │ └── book-1.md
|
||||
│ └── _index.md
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── book-1.md
|
||||
│ │ └── book-2.md
|
||||
│ └── _index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When rendering content/en/books/book-1.md:
|
||||
|
||||
```go-html-template
|
||||
{{ .IsTranslated }} → true
|
||||
```
|
||||
|
||||
When rendering content/en/books/book-2.md:
|
||||
|
||||
```go-html-template
|
||||
{{ .IsTranslated }} → false
|
||||
```
|
||||
46
docs/content/en/methods/page/Keywords.md
Normal file
46
docs/content/en/methods/page/Keywords.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Keywords
|
||||
description: Returns a slice of keywords as defined in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: '[]string'
|
||||
signatures: [PAGE.Keywords]
|
||||
---
|
||||
|
||||
By default, Hugo evaluates the keywords when creating collections of [related content].
|
||||
|
||||
[related content]: /content-management/related
|
||||
|
||||
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
|
||||
title = 'How to make spicy tuna hand rolls'
|
||||
keywords = ['tuna','sriracha','nori','rice']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To list the keywords within a template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Keywords }}
|
||||
{{ . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Or use the [delimit] function:
|
||||
|
||||
```go-html-template
|
||||
{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
|
||||
```
|
||||
|
||||
[delimit]: /functions/collections/delimit
|
||||
|
||||
Keywords are also a useful [taxonomy]:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[taxonomies]
|
||||
tag = 'tags'
|
||||
keyword = 'keywords'
|
||||
category = 'categories'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[taxonomy]: /content-management/taxonomies
|
||||
35
docs/content/en/methods/page/Kind.md
Normal file
35
docs/content/en/methods/page/Kind.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Kind
|
||||
description: Returns the kind of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Type
|
||||
returnType: string
|
||||
signatures: [PAGE.Kind]
|
||||
---
|
||||
|
||||
The [page kind] is one of `home`, `page`, `section`, `taxonomy`, or `term`.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
│ │ └── index.md <-- kind = page
|
||||
│ ├── book-2.md <-- kind = page
|
||||
│ └── _index.md <-- kind = section
|
||||
├── tags/
|
||||
│ ├── fiction/
|
||||
│ │ └── _index.md <-- kind = term
|
||||
│ └── _index.md <-- kind = taxonomy
|
||||
└── _index.md <-- kind = home
|
||||
```
|
||||
|
||||
To get the value within a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .Kind }}
|
||||
```
|
||||
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
65
docs/content/en/methods/page/Language.md
Normal file
65
docs/content/en/methods/page/Language.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Language
|
||||
description: Returns the language object for the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/site/Language
|
||||
returnType: langs.Language
|
||||
signatures: [PAGE.Language]
|
||||
---
|
||||
|
||||
The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration.
|
||||
|
||||
You can also use the `Language` method on a `Site` object. See [details].
|
||||
|
||||
## Methods
|
||||
|
||||
The examples below assume the following in your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.de]
|
||||
languageCode = 'de-DE'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Deutsch'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Lang
|
||||
: (`string`) The language tag as defined by [RFC 5646].
|
||||
|
||||
```go-html-template
|
||||
{{ .Language.Lang }} → de
|
||||
```
|
||||
|
||||
LanguageCode
|
||||
: (`string`) The language code from the site configuration.
|
||||
|
||||
```go-html-template
|
||||
{{ .Language.LanguageCode }} → de-DE
|
||||
```
|
||||
|
||||
LanguageDirection
|
||||
: (`string`) The language direction from the site configuration, either `ltr` or `rtl`.
|
||||
|
||||
```go-html-template
|
||||
{{ .Language.LanguageDirection }} → ltr
|
||||
```
|
||||
|
||||
LanguageName
|
||||
: (`string`) The language name from the site configuration.
|
||||
|
||||
```go-html-template
|
||||
{{ .Language.LanguageName }} → Deutsch
|
||||
```
|
||||
|
||||
Weight
|
||||
: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
|
||||
|
||||
```go-html-template
|
||||
{{ .Language.Weight }} → 2
|
||||
```
|
||||
|
||||
[details]: /methods/site/language
|
||||
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
|
||||
40
docs/content/en/methods/page/Lastmod.md
Normal file
40
docs/content/en/methods/page/Lastmod.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Lastmod
|
||||
description: Returns the last modification date of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Date
|
||||
- methods/page/ExpiryDate
|
||||
- methods/page/PublishDate
|
||||
- methods/page/GitInfo
|
||||
returnType: time.Time
|
||||
signatures: [PAGE.Lastmod]
|
||||
---
|
||||
|
||||
Set the last modification date in front matter:
|
||||
|
||||
{{< code-toggle file=content/news/article-1.md fm=true >}}
|
||||
title = 'Article 1'
|
||||
lastmod = 2023-10-19T00:40:04-07:00
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The last modification date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
|
||||
|
||||
```go-html-template
|
||||
{{ .Lastmod | time.Format ":date_medium" }} → Oct 19, 2023
|
||||
```
|
||||
|
||||
In the example above we explicitly set the last modification date in front matter. With Hugo's default configuration, the `Lastmod` method returns the front matter value. This behavior is configurable, allowing you to:
|
||||
|
||||
- Set the last modification date to the Author Date of the last Git commit for that file. See [`GitInfo`] for details.
|
||||
- Set fallback values if the last modification date is not defined in front matter.
|
||||
|
||||
Learn more about [date configuration].
|
||||
|
||||
[`gitinfo`]: /methods/page/gitinfo
|
||||
[`time.format`]: /functions/time/format
|
||||
[date configuration]: /getting-started/configuration/#configure-dates
|
||||
[time methods]: /methods/time
|
||||
[time.time]: https://pkg.go.dev/time#time
|
||||
40
docs/content/en/methods/page/Layout.md
Normal file
40
docs/content/en/methods/page/Layout.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Layout
|
||||
description: Returns the layout for the given page as defined in front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Type
|
||||
returnType: string
|
||||
signatures: [PAGE.Layout]
|
||||
---
|
||||
|
||||
Specify the `layout` field in front matter to target a particular template. See [details].
|
||||
|
||||
[details]: /templates/lookup-order/#target-a-template
|
||||
|
||||
{{< code-toggle file=content/contact.md >}}
|
||||
title = 'Contact'
|
||||
layout = 'contact'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Hugo will render the page using contact.html.
|
||||
|
||||
```text
|
||||
layouts/
|
||||
└── _default/
|
||||
├── baseof.html
|
||||
├── contact.html
|
||||
├── home.html
|
||||
├── list.html
|
||||
└── single.html
|
||||
```
|
||||
|
||||
Although rarely used within a template, you can access the value with:
|
||||
|
||||
```go-html-template
|
||||
{{ .Layout }}
|
||||
```
|
||||
|
||||
The `Layout` method returns an empty string if the `layout` field in front matter is not defined.
|
||||
15
docs/content/en/methods/page/Len.md
Normal file
15
docs/content/en/methods/page/Len.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Len
|
||||
description: Returns the length, in bytes, of the rendered content of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Content
|
||||
returnType: int
|
||||
signatures: [PAGE.Len]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ .Len }} → 42
|
||||
```
|
||||
30
docs/content/en/methods/page/LinkTitle.md
Normal file
30
docs/content/en/methods/page/LinkTitle.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: LinkTitle
|
||||
description: Returns the link title of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Title
|
||||
returnType: string
|
||||
signatures: [PAGE.LinkTitle]
|
||||
---
|
||||
|
||||
The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method.
|
||||
|
||||
[`Title`]: /methods/page/title
|
||||
|
||||
{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
|
||||
title = 'Seventeen delightful recipes for healthy desserts'
|
||||
linkTitle = 'Dessert recipes'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
```go-html-template
|
||||
{{ .LinkTitle }} → Dessert recipes
|
||||
```
|
||||
|
||||
As demonstrated above, defining a link title in front matter is advantageous when the page title is long. Use it when generating anchor elements in your templates:
|
||||
|
||||
```go-html-template
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
```
|
||||
53
docs/content/en/methods/page/Next.md
Normal file
53
docs/content/en/methods/page/Next.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Next
|
||||
description: Returns the next page in a global page collection, relative to the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Prev
|
||||
- methods/page/NextInSection
|
||||
- methods/page/PrevInSection
|
||||
- methods/pages/Next
|
||||
- methods/pages/Prev
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.Next]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
When you visit page-2:
|
||||
|
||||
- The `Prev` method points to page-3
|
||||
- The `Next` method points to page-1
|
||||
|
||||
{{% note %}}
|
||||
Use the opposite label in your navigation links as shown in the example below.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Next }}
|
||||
<a href="{{ .RelPermalink }}">Prev</a>
|
||||
{{ end }}
|
||||
|
||||
{{ with .Prev }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Compare to Pages methods
|
||||
|
||||
{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}}
|
||||
71
docs/content/en/methods/page/NextInSection.md
Normal file
71
docs/content/en/methods/page/NextInSection.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: NextInSection
|
||||
description: Returns the next page within a section, relative to the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/PrevInSection
|
||||
- methods/page/Next
|
||||
- methods/page/Prev
|
||||
- methods/pages/Next
|
||||
- methods/pages/Prev
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.NextInSection]
|
||||
---
|
||||
|
||||
The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.md
|
||||
│ ├── book-1.md
|
||||
│ ├── book-2.md
|
||||
│ └── book-3.md
|
||||
├── films/
|
||||
│ ├── _index.md
|
||||
│ ├── film-1.md
|
||||
│ ├── film-2.md
|
||||
│ └── film-3.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When you visit book-2:
|
||||
|
||||
- The `PrevInSection` method points to book-3
|
||||
- The `NextInSection` method points to book-1
|
||||
|
||||
{{% note %}}
|
||||
Use the opposite label in your navigation links as shown in the example below.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .NextInSection }}
|
||||
<a href="{{ .RelPermalink }}">Previous in section</a>
|
||||
{{ end }}
|
||||
|
||||
{{ with .PrevInSection }}
|
||||
<a href="{{ .RelPermalink }}">Next in section</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The navigation sort order may be different than the page collection sort order.
|
||||
{{% /note %}}
|
||||
|
||||
With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence:
|
||||
|
||||
1. Page [weight]
|
||||
2. Page [date] (descending)
|
||||
3. Page [linkTitle], falling back to page [title]
|
||||
4. Page file path if the page is backed by a file
|
||||
|
||||
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
|
||||
|
||||
[date]: /methods/page/date
|
||||
[weight]: /methods/page/weight
|
||||
[linkTitle]: /methods/page/linktitle
|
||||
[title]: /methods/page/title
|
||||
40
docs/content/en/methods/page/OutputFormats.md
Normal file
40
docs/content/en/methods/page/OutputFormats.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: OutputFormats
|
||||
description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/AlternativeOutputFormats
|
||||
returnType: '[]OutputFormat'
|
||||
signatures: [PAGE.OutputFormats]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/output-format-definition.md" %}}
|
||||
|
||||
The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/templates/output-formats/).
|
||||
|
||||
## Methods
|
||||
|
||||
{{% include "methods/page/_common/output-format-methods.md" %}}
|
||||
|
||||
## Example
|
||||
|
||||
To link to the RSS feed for the current page:
|
||||
|
||||
```go-html-template
|
||||
{{ with .OutputFormats.Get "rss" -}}
|
||||
<a href="{{ .RelPermalink }}">RSS Feed</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
On the site's home page, Hugo renders this to:
|
||||
|
||||
```html
|
||||
<a href="/index.xml">RSS Feed</a>
|
||||
```
|
||||
|
||||
Please see the [link to output formats] section to understand the importance of the construct above.
|
||||
|
||||
[link to output formats]: /templates/output-formats/#link-to-output-formats
|
||||
40
docs/content/en/methods/page/Page.md
Normal file
40
docs/content/en/methods/page/Page.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Page
|
||||
description: Returns the Page object of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.Page]
|
||||
---
|
||||
|
||||
This is a convenience method, useful within partial templates that are called from both [shortcodes] and page templates.
|
||||
|
||||
{{< code file=layouts/shortcodes/foo.html >}}
|
||||
{{ partial "my-partial.html" . }}
|
||||
{{< /code >}}
|
||||
|
||||
When the shortcode calls the partial, it passes the current [context] (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ partial "my-partial.html" . }}
|
||||
{{< /code >}}
|
||||
|
||||
When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
|
||||
|
||||
{{< code file=layouts/partials/my-partial.html >}}
|
||||
The page title is: {{ .Page.Title }}
|
||||
{{< /code >}}
|
||||
|
||||
To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`.
|
||||
|
||||
{{% note %}}
|
||||
And yes, that means you can do `.Page.Page.Page.Page.Title` too.
|
||||
|
||||
But don't.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
[context]: getting-started/glossary/#context
|
||||
[shortcodes]: /getting-started/glossary/#shortcode
|
||||
90
docs/content/en/methods/page/Pages.md
Normal file
90
docs/content/en/methods/page/Pages.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Pages
|
||||
description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/RegularPages
|
||||
- methods/page/RegularPagesRecursive
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.Pages]
|
||||
---
|
||||
|
||||
The `Pages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
|
||||
|
||||
Range through the page collection in your template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Pages.ByTitle }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── lessons/
|
||||
│ ├── lesson-1/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── lesson-2/
|
||||
│ │ ├── resources/
|
||||
│ │ │ ├── task-list.md
|
||||
│ │ │ └── worksheet.md
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── _index.md
|
||||
│ ├── grading-policy.md
|
||||
│ └── lesson-plan.md
|
||||
├── _index.md
|
||||
├── contact.md
|
||||
└── legal.md
|
||||
```
|
||||
|
||||
When rendering the home page, the `Pages` method returns:
|
||||
|
||||
contact.md
|
||||
legal.md
|
||||
lessons/_index.md
|
||||
|
||||
When rendering the lessons page, the `Pages` method returns:
|
||||
|
||||
lessons/grading-policy.md
|
||||
lessons/lesson-plan.md
|
||||
lessons/lesson-1/_index.md
|
||||
lessons/lesson-2/_index.md
|
||||
|
||||
When rendering lesson-1, the `Pages` method returns:
|
||||
|
||||
lessons/lesson-1/part-1.md
|
||||
lessons/lesson-1/part-2.md
|
||||
|
||||
When rendering lesson-2, the `Pages` method returns:
|
||||
|
||||
lessons/lesson-2/part-1.md
|
||||
lessons/lesson-2/part-2.md
|
||||
lessons/lesson-2/resources/task-list.md
|
||||
lessons/lesson-2/resources/worksheet.md
|
||||
|
||||
In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
|
||||
|
||||
{{% note %}}
|
||||
When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
|
||||
|
||||
[details]: /methods/site/pages
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.Pages.ByTitle }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[collection]: /getting-started/glossary/#collection
|
||||
[context]: /getting-started/glossary/#context
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
[section]: /getting-started/glossary/#section
|
||||
50
docs/content/en/methods/page/Paginate.md
Normal file
50
docs/content/en/methods/page/Paginate.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Paginate
|
||||
description: Paginates a collection of pages.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Paginator
|
||||
returnType: page.Pager
|
||||
signatures: ['PAGE.Paginate COLLECTION [N]']
|
||||
---
|
||||
|
||||
[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
|
||||
|
||||
By default, the number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`. Override the value in your site configuration by providing a second argument, an integer, when calling the `Paginate` method.
|
||||
|
||||
{{% note %}}
|
||||
There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
|
||||
|
||||
The `Paginate` method is more flexible.
|
||||
{{% /note %}}
|
||||
|
||||
You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates.
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ $pages := where .Site.RegularPages "Section" "articles" }}
|
||||
{{ $pages = $pages.ByTitle }}
|
||||
{{ range (.Paginate $pages 7).Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
{{< /code >}}
|
||||
|
||||
In the example above, we:
|
||||
|
||||
1. Build a page collection
|
||||
2. Sort the collection by title
|
||||
3. Paginate the collection, with 7 elements per pager
|
||||
4. Range over the paginated page collection, rendering a link to each page
|
||||
5. Call the internal "pagination" template to create the navigation links between pagers.
|
||||
|
||||
{{% note %}}
|
||||
Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
[pagination]: /templates/pagination/
|
||||
[`section`]: /getting-started/glossary/#section
|
||||
[`taxonomy`]: /getting-started/glossary/#taxonomy
|
||||
[`term`]: /getting-started/glossary/#term
|
||||
42
docs/content/en/methods/page/Paginator.md
Normal file
42
docs/content/en/methods/page/Paginator.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Paginator
|
||||
description: Paginates the collection of regular pages received in context.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Paginate
|
||||
returnType: page.Pager
|
||||
signatures: [PAGE.Paginator]
|
||||
---
|
||||
|
||||
[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`.
|
||||
|
||||
You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates. Each of these receive a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context.
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ range .Paginator.Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
{{< /code >}}
|
||||
|
||||
In the example above, the internal "pagination" template creates the navigation links between pagers.
|
||||
|
||||
{{% note %}}
|
||||
Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
|
||||
|
||||
The [`Paginate`] method is more flexible, and strongly recommended.
|
||||
|
||||
[`paginate`]: /methods/page/paginate
|
||||
{{% /note %}}
|
||||
|
||||
{{% note %}}
|
||||
Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
[pagination]: /templates/pagination/
|
||||
[`section`]: /getting-started/glossary/#section
|
||||
[`taxonomy`]: /getting-started/glossary/#taxonomy
|
||||
[`term`]: /getting-started/glossary/#term
|
||||
47
docs/content/en/methods/page/Param.md
Normal file
47
docs/content/en/methods/page/Param.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Param
|
||||
description: Returns a page parameter with the given key, falling back to a site parameter if present.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType: any
|
||||
signatures: [PAGE.Param KEY]
|
||||
aliases: [/functions/param]
|
||||
---
|
||||
|
||||
The `Param` method on a `Page` object looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `Param` method returns `nil`.
|
||||
|
||||
Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level.
|
||||
|
||||
For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed:
|
||||
|
||||
Configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params]
|
||||
display_toc = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Content:
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = 'Example'
|
||||
date = 2023-01-01
|
||||
draft = false
|
||||
display_toc = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Template:
|
||||
|
||||
```go-html-template
|
||||
{{ if .Param "display_toc" }}
|
||||
{{ .TableOfContents }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The `Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead:
|
||||
|
||||
```go-html-template
|
||||
{{ or .Params.foo site.Params.foo }}
|
||||
```
|
||||
43
docs/content/en/methods/page/Params.md
Normal file
43
docs/content/en/methods/page/Params.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Params
|
||||
description: Returns a map of custom parameters as defined in the front matter of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/collections/IndexFunction
|
||||
- methods/site/Params
|
||||
- methods/page/Param
|
||||
returnType: maps.Params
|
||||
signatures: [PAGE.Params]
|
||||
---
|
||||
|
||||
With this front matter:
|
||||
|
||||
{{< code-toggle file=content/news/annual-conference.md >}}
|
||||
title = 'Annual conference'
|
||||
date = 2023-10-17T15:11:37-07:00
|
||||
display_related = true
|
||||
[params.author]
|
||||
email = 'jsmith@example.org'
|
||||
name = 'John Smith'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The `title` and `date` fields are standard parameters---the other fields are user-defined.
|
||||
|
||||
Access the custom parameters by [chaining] the [identifiers]:
|
||||
|
||||
```go-html-template
|
||||
{{ .Params.display_related }} → true
|
||||
{{ .Params.author.name }} → John Smith
|
||||
```
|
||||
|
||||
In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
|
||||
|
||||
```go-html-template
|
||||
{{ index .Params "key-with-hyphens" }} → 2023
|
||||
```
|
||||
|
||||
[`index`]: /functions/collections/indexfunction
|
||||
[chaining]: /getting-started/glossary/#chain
|
||||
[identifiers]: /getting-started/glossary/#identifier
|
||||
60
docs/content/en/methods/page/Parent.md
Normal file
60
docs/content/en/methods/page/Parent.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Parent
|
||||
description: Returns the Page object of the parent section of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ancestors
|
||||
- methods/page/CurrentSection
|
||||
- methods/page/FirstSection
|
||||
- methods/page/InSection
|
||||
- methods/page/IsAncestor
|
||||
- methods/page/IsDescendant
|
||||
- methods/page/Sections
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.Parent]
|
||||
---
|
||||
|
||||
{{% include "methods/page/_common/definition-of-section.md" %}}
|
||||
|
||||
{{% note %}}
|
||||
The parent section of a regular page is the [current section].
|
||||
|
||||
[current section]: /methods/page/currentsection
|
||||
{{% /note %}}
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── auctions/
|
||||
│ ├── 2023-11/
|
||||
│ │ ├── _index.md <-- parent: auctions
|
||||
│ │ ├── auction-1.md
|
||||
│ │ └── auction-2.md <-- parent: 2023-11
|
||||
│ ├── 2023-12/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── auction-3.md
|
||||
│ │ └── auction-4.md
|
||||
│ ├── _index.md <-- parent: home
|
||||
│ ├── bidding.md
|
||||
│ └── payment.md <-- parent: auctions
|
||||
├── books/
|
||||
│ ├── _index.md <-- parent: home
|
||||
│ ├── book-1.md
|
||||
│ └── book-2.md <-- parent: books
|
||||
├── films/
|
||||
│ ├── _index.md <-- parent: home
|
||||
│ ├── film-1.md
|
||||
│ └── film-2.md <-- parent: films
|
||||
└── _index.md <-- parent: nil
|
||||
```
|
||||
|
||||
In the example above, note the parent section of the home page is nil. Code defensively by verifying existence of the parent section before calling methods on its `Page` object. To create a link to the parent section page of the current page:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Parent }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
25
docs/content/en/methods/page/Permalink.md
Normal file
25
docs/content/en/methods/page/Permalink.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Permalink
|
||||
description: Returns the permalink of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/RelPermalink
|
||||
returnType: string
|
||||
signatures: [PAGE.Permalink]
|
||||
---
|
||||
|
||||
Site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
title = 'Documentation'
|
||||
baseURL = 'https://example.org/docs/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Template:
|
||||
|
||||
```go-html-template
|
||||
{{ $page := .Site.GetPage "/about" }}
|
||||
{{ $page.Permalink }} → https://example.org/docs/about/
|
||||
```
|
||||
28
docs/content/en/methods/page/Plain.md
Normal file
28
docs/content/en/methods/page/Plain.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Plain
|
||||
description: Returns the rendered content of the given page, removing all HTML tags.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Content
|
||||
- methods/page/RawContent
|
||||
- methods/page/PlainWords
|
||||
- methods/page/RenderShortcodes
|
||||
returnType: string
|
||||
signatures: [PAGE.Plain]
|
||||
---
|
||||
|
||||
The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
|
||||
|
||||
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
|
||||
|
||||
```go-html-template
|
||||
{{ .Plain | htmlUnescape }}
|
||||
```
|
||||
|
||||
[shortcodes]: /getting-started/glossary/#shortcode
|
||||
[html/template]: https://pkg.go.dev/html/template
|
||||
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
|
||||
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
|
||||
[`htmlUnescape`]: /functions/
|
||||
36
docs/content/en/methods/page/PlainWords.md
Normal file
36
docs/content/en/methods/page/PlainWords.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: PlainWords
|
||||
description: Calls the Plain method, splits the result into a slice of words, and returns the slice.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Content
|
||||
- methods/page/RawContent
|
||||
- methods/page/Plain
|
||||
returnType: '[]string'
|
||||
signatures: [PAGE.PlainWords]
|
||||
---
|
||||
|
||||
The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
|
||||
|
||||
{{% note %}}
|
||||
_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._
|
||||
|
||||
[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
|
||||
{{% /note %}}
|
||||
|
||||
As a result, elements within the slice may contain leading or trailing punctuation.
|
||||
|
||||
```go-html-template
|
||||
{{ .PlainWords }}
|
||||
```
|
||||
|
||||
To determine the approximate number of unique words on a page:
|
||||
|
||||
```go-html-template
|
||||
{{ .PlainWords | uniq }} → 42
|
||||
```
|
||||
|
||||
[`Plain`]: /methods/page/plain
|
||||
[`strings.Fields`]: https://pkg.go.dev/strings#Fields
|
||||
53
docs/content/en/methods/page/Prev.md
Normal file
53
docs/content/en/methods/page/Prev.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Prev
|
||||
description: Returns the previous page in a global page collection, relative to the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Next
|
||||
- methods/page/PrevInSection
|
||||
- methods/page/NextInSection
|
||||
- methods/pages/Prev
|
||||
- methods/pages/Next
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.Prev]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
When you visit page-2:
|
||||
|
||||
- The `Prev` method points to page-3
|
||||
- The `Next` method points to page-1
|
||||
|
||||
{{% note %}}
|
||||
Use the opposite label in your navigation links as shown in the example below.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .Next }}
|
||||
<a href="{{ .RelPermalink }}">Prev</a>
|
||||
{{ end }}
|
||||
|
||||
{{ with .Prev }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Compare to Pages methods
|
||||
|
||||
{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}}
|
||||
72
docs/content/en/methods/page/PrevInSection.md
Normal file
72
docs/content/en/methods/page/PrevInSection.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: PrevInSection
|
||||
description: Returns the previous page within a section, relative to the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/NextInSection
|
||||
- methods/page/Next
|
||||
- methods/pages/Next
|
||||
- methods/page/Prev
|
||||
- methods/pages/Prev
|
||||
returnType: page.Page
|
||||
signatures: [PAGE.PrevInSection]
|
||||
---
|
||||
|
||||
|
||||
The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.md
|
||||
│ ├── book-1.md
|
||||
│ ├── book-2.md
|
||||
│ └── book-3.md
|
||||
├── films/
|
||||
│ ├── _index.md
|
||||
│ ├── film-1.md
|
||||
│ ├── film-2.md
|
||||
│ └── film-3.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
When you visit book-2:
|
||||
|
||||
- The `PrevInSection` method points to book-3
|
||||
- The `NextInSection` method points to book-1
|
||||
|
||||
{{% note %}}
|
||||
Use the opposite label in your navigation links as shown in the example below.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with .NextInSection }}
|
||||
<a href="{{ .RelPermalink }}">Previous in section</a>
|
||||
{{ end }}
|
||||
|
||||
{{ with .PrevInSection }}
|
||||
<a href="{{ .RelPermalink }}">Next in section</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The navigation sort order may be different than the page collection sort order.
|
||||
{{% /note %}}
|
||||
|
||||
With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence:
|
||||
|
||||
1. Page [weight]
|
||||
2. Page [date] (descending)
|
||||
3. Page [linkTitle], falling back to page [title]
|
||||
4. Page file path if the page is backed by a file
|
||||
|
||||
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
|
||||
|
||||
[date]: /methods/page/date
|
||||
[weight]: /methods/page/weight
|
||||
[linkTitle]: /methods/page/linktitle
|
||||
[title]: /methods/page/title
|
||||
35
docs/content/en/methods/page/PublishDate.md
Normal file
35
docs/content/en/methods/page/PublishDate.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: PublishDate
|
||||
description: Returns the publish date of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Date
|
||||
- methods/page/ExpiryDate
|
||||
- methods/page/LastMod
|
||||
returnType: time.Time
|
||||
signatures: [PAGE.PublishDate]
|
||||
---
|
||||
|
||||
By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag.
|
||||
|
||||
Set the publish date in front matter:
|
||||
|
||||
{{< code-toggle file=content/news/article-1.md fm=true >}}
|
||||
title = 'Article 1'
|
||||
publishDate = 2023-10-19T00:40:04-07:00
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The publish date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
|
||||
|
||||
```go-html-template
|
||||
{{ .PublishDate | time.Format ":date_medium" }} → Oct 19, 2023
|
||||
```
|
||||
|
||||
In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details].
|
||||
|
||||
[`time.Format`]: /functions/time/format
|
||||
[details]: /getting-started/configuration/#configure-dates
|
||||
[time methods]: /methods/time
|
||||
[time.Time]: https://pkg.go.dev/time#Time
|
||||
31
docs/content/en/methods/page/RawContent.md
Normal file
31
docs/content/en/methods/page/RawContent.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: RawContent
|
||||
description: Returns the raw content of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Content
|
||||
- methods/page/Plain
|
||||
- methods/page/PlainWords
|
||||
- methods/page/RenderShortcodes
|
||||
returnType: string
|
||||
signatures: [PAGE.RawContent]
|
||||
---
|
||||
|
||||
The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter.
|
||||
|
||||
```go-html-template
|
||||
{{ .RawContent }}
|
||||
```
|
||||
|
||||
This is useful when rendering a page in a plain text [output format].
|
||||
|
||||
{{% note %}}
|
||||
[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
|
||||
|
||||
[shortcodes]: /getting-started/glossary/#shortcode
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
{{% /note %}}
|
||||
|
||||
[output format]: /templates/output-formats
|
||||
49
docs/content/en/methods/page/ReadingTime.md
Normal file
49
docs/content/en/methods/page/ReadingTime.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: ReadingTime
|
||||
description: Returns the estimated reading time, in minutes, for the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/WordCount
|
||||
- methods/page/FuzzyWordCount
|
||||
returnType: int
|
||||
signatures: [PAGE.ReadingTime]
|
||||
---
|
||||
|
||||
The estimated reading time is calculated by dividing the number of words in the content by the reading speed.
|
||||
|
||||
By default, Hugo assumes a reading speed of 212 words per minute. For CJK languages, it assumes 500 words per minute.
|
||||
|
||||
```go-html-template
|
||||
{{ printf "Estimated reading time: %d minutes" .ReadingTime }}
|
||||
```
|
||||
|
||||
Reading speed varies by language. Create language-specific estimated reading times on your multilingual site using site parameters.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages]
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 2
|
||||
[languages.de.params]
|
||||
reading_speed = 179
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
[languages.en.params]
|
||||
reading_speed = 228
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Then in your template:
|
||||
|
||||
```go-html-template
|
||||
{{ $readingTime := div (float .WordCount) .Site.Params.reading_speed }}
|
||||
{{ $readingTime = math.Ceil $readingTime }}
|
||||
```
|
||||
|
||||
We cast the `.WordCount` to a float to obtain a float when we divide by the reading speed. Then round up to the nearest integer.
|
||||
44
docs/content/en/methods/page/Ref.md
Normal file
44
docs/content/en/methods/page/Ref.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Ref
|
||||
description: Returns the absolute URL of the page with the given path, language, and output format.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/RelRef
|
||||
- functions/urls/RelRef
|
||||
- functions/urls/Ref
|
||||
returnType: string
|
||||
signatures: [PAGE.Ref OPTIONS]
|
||||
---
|
||||
|
||||
The map of option contains:
|
||||
|
||||
path
|
||||
: (`string`) The path to the page, relative to the content directory. Required.
|
||||
|
||||
lang
|
||||
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
|
||||
|
||||
outputFormat
|
||||
: (`string`) The output format to search for the page. Default is the current output format. Optional.
|
||||
|
||||
The examples below show the rendered output when visiting a page on the English language version of the site:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "path" "/books/book-1" }}
|
||||
{{ .Ref $opts }} → https://example.org/en/books/book-1/
|
||||
|
||||
{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
|
||||
{{ .Ref $opts }} → https://example.org/de/books/book-1/
|
||||
|
||||
{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
|
||||
{{ .Ref $opts }} → https://example.org/de/books/book-1/index.json
|
||||
```
|
||||
|
||||
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
refLinksErrorLevel = 'warning'
|
||||
refLinksNotFoundURL = '/some/other/url'
|
||||
{{< /code-toggle >}}
|
||||
87
docs/content/en/methods/page/RegularPages.md
Normal file
87
docs/content/en/methods/page/RegularPages.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: RegularPages
|
||||
description: Returns a collection of regular pages within the current section.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Pages
|
||||
- methods/page/RegularPagesRecursive
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.RegularPages]
|
||||
---
|
||||
|
||||
The `RegularPages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
|
||||
|
||||
Range through the page collection in your template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .RegularPages.ByTitle }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── lessons/
|
||||
│ ├── lesson-1/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── lesson-2/
|
||||
│ │ ├── resources/
|
||||
│ │ │ ├── task-list.md
|
||||
│ │ │ └── worksheet.md
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── _index.md
|
||||
│ ├── grading-policy.md
|
||||
│ └── lesson-plan.md
|
||||
├── _index.md
|
||||
├── contact.md
|
||||
└── legal.md
|
||||
```
|
||||
|
||||
When rendering the home page, the `RegularPages` method returns:
|
||||
|
||||
contact.md
|
||||
legal.md
|
||||
|
||||
When rendering the lessons page, the `RegularPages` method returns:
|
||||
|
||||
lessons/grading-policy.md
|
||||
lessons/lesson-plan.md
|
||||
|
||||
When rendering lesson-1, the `RegularPages` method returns:
|
||||
|
||||
lessons/lesson-1/part-1.md
|
||||
lessons/lesson-1/part-2.md
|
||||
|
||||
When rendering lesson-2, the `RegularPages` method returns:
|
||||
|
||||
lessons/lesson-2/part-1.md
|
||||
lessons/lesson-2/part-2.md
|
||||
lessons/lesson-2/resources/task-list.md
|
||||
lessons/lesson-2/resources/worksheet.md
|
||||
|
||||
In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
|
||||
|
||||
{{% note %}}
|
||||
When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
|
||||
|
||||
[details]: /methods/site/regularpages
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.RegularPages.ByTitle }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[collection]: /getting-started/glossary/#collection
|
||||
[context]: /getting-started/glossary/#context
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
[section]: /getting-started/glossary/#section
|
||||
90
docs/content/en/methods/page/RegularPagesRecursive.md
Normal file
90
docs/content/en/methods/page/RegularPagesRecursive.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: RegularPagesRecursive
|
||||
description: Returns a collection of regular pages within the current section, and regular pages within all descendant sections.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Pages
|
||||
- methods/page/RegularPages
|
||||
returnType: page.Pages
|
||||
signatures: [PAGE.RegularPagesRecursive]
|
||||
---
|
||||
|
||||
The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
|
||||
|
||||
Range through the page collection in your template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .RegularPagesRecursive.ByTitle }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Consider this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── lessons/
|
||||
│ ├── lesson-1/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── lesson-2/
|
||||
│ │ ├── resources/
|
||||
│ │ │ ├── task-list.md
|
||||
│ │ │ └── worksheet.md
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── part-1.md
|
||||
│ │ └── part-2.md
|
||||
│ ├── _index.md
|
||||
│ ├── grading-policy.md
|
||||
│ └── lesson-plan.md
|
||||
├── _index.md
|
||||
├── contact.md
|
||||
└── legal.md
|
||||
```
|
||||
|
||||
When rendering the home page, the `RegularPagesRecursive` method returns:
|
||||
|
||||
contact.md
|
||||
lessons/grading-policy.md
|
||||
legal.md
|
||||
lessons/lesson-plan.md
|
||||
lessons/lesson-2/part-1.md
|
||||
lessons/lesson-1/part-1.md
|
||||
lessons/lesson-2/part-2.md
|
||||
lessons/lesson-1/part-2.md
|
||||
lessons/lesson-2/resources/task-list.md
|
||||
lessons/lesson-2/resources/worksheet.md
|
||||
|
||||
When rendering the lessons page, the `RegularPagesRecursive` method returns:
|
||||
|
||||
lessons/grading-policy.md
|
||||
lessons/lesson-plan.md
|
||||
lessons/lesson-2/part-1.md
|
||||
lessons/lesson-1/part-1.md
|
||||
lessons/lesson-2/part-2.md
|
||||
lessons/lesson-1/part-2.md
|
||||
lessons/lesson-2/resources/task-list.md
|
||||
lessons/lesson-2/resources/worksheet.md
|
||||
|
||||
When rendering lesson-1, the `RegularPagesRecursive` method returns:
|
||||
|
||||
lessons/lesson-1/part-1.md
|
||||
lessons/lesson-1/part-2.md
|
||||
|
||||
When rendering lesson-2, the `RegularPagesRecursive` method returns:
|
||||
|
||||
lessons/lesson-2/part-1.md
|
||||
lessons/lesson-2/part-2.md
|
||||
lessons/lesson-2/resources/task-list.md
|
||||
lessons/lesson-2/resources/worksheet.md
|
||||
|
||||
{{% note %}}
|
||||
The `RegularPagesRecursive` method in not available on a `Site` object.
|
||||
{{% /note %}}
|
||||
|
||||
[collection]: /getting-started/glossary/#collection
|
||||
[context]: /getting-started/glossary/#context
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
25
docs/content/en/methods/page/RelPermalink.md
Normal file
25
docs/content/en/methods/page/RelPermalink.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: RelPermalink
|
||||
description: Returns the relative permalink of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Permalink
|
||||
returnType: string
|
||||
signatures: [PAGE.RelPermalink]
|
||||
---
|
||||
|
||||
Site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
title = 'Documentation'
|
||||
baseURL = 'https://example.org/docs/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Template:
|
||||
|
||||
```go-html-template
|
||||
{{ $page := .Site.GetPage "/about" }}
|
||||
{{ $page.RelPermalink }} → /docs/about/
|
||||
```
|
||||
44
docs/content/en/methods/page/RelRef.md
Normal file
44
docs/content/en/methods/page/RelRef.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: RelRef
|
||||
description: Returns the relative URL of the page with the given path, language, and output format.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/Ref
|
||||
- functions/urls/Ref
|
||||
- functions/urls/RelRef
|
||||
returnType: string
|
||||
signatures: [PAGE.RelRef OPTIONS]
|
||||
---
|
||||
|
||||
The map of option contains:
|
||||
|
||||
path
|
||||
: (`string`) The path to the page, relative to the content directory. Required.
|
||||
|
||||
lang
|
||||
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
|
||||
|
||||
outputFormat
|
||||
: (`string`) The output format to search for the page. Default is the current output format. Optional.
|
||||
|
||||
The examples below show the rendered output when visiting a page on the English language version of the site:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "path" "/books/book-1" }}
|
||||
{{ .RelRef $opts }} → /en/books/book-1/
|
||||
|
||||
{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
|
||||
{{ .RelRef $opts }} → /de/books/book-1/
|
||||
|
||||
{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
|
||||
{{ .RelRef $opts }} → /de/books/book-1/index.json
|
||||
```
|
||||
|
||||
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
refLinksErrorLevel = 'warning'
|
||||
refLinksNotFoundURL = '/some/other/url'
|
||||
{{< /code-toggle >}}
|
||||
75
docs/content/en/methods/page/Render.md
Normal file
75
docs/content/en/methods/page/Render.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Render
|
||||
description: Renders the given template with the given page as context.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/partials/Include
|
||||
- functions/partials/IncludeCached
|
||||
returnType: template.HTML
|
||||
signatures: [PAGE.Render NAME]
|
||||
aliases: [/functions/render]
|
||||
---
|
||||
|
||||
Typically used when ranging over a page collection, the `Render` method on a `Page` object renders the given template, passing the given page as context.
|
||||
|
||||
```go-html-template
|
||||
{{ range site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In the example above, note that the template ("summary") is identified by its file name without directory or extension.
|
||||
|
||||
Although similar to the [`partial`] function, there are key differences.
|
||||
|
||||
`Render` method|`partial` function|
|
||||
:--|:--
|
||||
The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
|
||||
The path to the template is determined by the [content type].|You must specify the path to the template, relative to the layouts/partials directory.
|
||||
|
||||
Consider this layout structure:
|
||||
|
||||
```text
|
||||
layouts/
|
||||
├── _default/
|
||||
│ ├── baseof.html
|
||||
│ ├── home.html
|
||||
│ ├── li.html <-- used for other content types
|
||||
│ ├── list.html
|
||||
│ ├── single.html
|
||||
│ └── summary.html
|
||||
└── books/
|
||||
├── li.html <-- used when content type is "books"
|
||||
└── summary.html
|
||||
```
|
||||
|
||||
And this template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range site.RegularPages.ByDate }}
|
||||
{{ .Render "li" }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
When rendering content of type "books" the `Render` method calls:
|
||||
|
||||
```text
|
||||
layouts/books/li.html
|
||||
```
|
||||
|
||||
For all other content types the `Render` methods calls:
|
||||
|
||||
```text
|
||||
layouts/_default/li.html
|
||||
```
|
||||
|
||||
See [content views] for more examples.
|
||||
|
||||
[content views]: /templates/views
|
||||
[`partial`]: /functions/partials/include
|
||||
[content type]: /getting-started/glossary/#content-type
|
||||
78
docs/content/en/methods/page/RenderShortcodes.md
Normal file
78
docs/content/en/methods/page/RenderShortcodes.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: RenderShortcodes
|
||||
description: Renders all shortcodes in the content of the given page, preserving the surrounding markup.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- methods/page/RenderString
|
||||
- methods/page/Content
|
||||
- methods/page/RawContent
|
||||
- methods/page/Plain
|
||||
- methods/page/PlainWords
|
||||
returnType: template.HTML
|
||||
signatures: [PAGE.RenderShortcodes]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.117.0 >}}
|
||||
|
||||
Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
|
||||
|
||||
For example:
|
||||
|
||||
{{< code file=layouts/shortcodes/include.html >}}
|
||||
{{ $p := site.GetPage (.Get 0) }}
|
||||
{{ $p.RenderShortcodes }}
|
||||
{{< /code >}}
|
||||
|
||||
Then in your markdown:
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{%/* include "/snippets/services.md" */%}}
|
||||
{{%/* include "/snippets/values.md" */%}}
|
||||
{{%/* include "/snippets/leadership.md" */%}}
|
||||
{{< /code >}}
|
||||
|
||||
Each of the included markdown files can contain calls to other shortcodes.
|
||||
|
||||
## Shortcode notation
|
||||
|
||||
In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
|
||||
|
||||
- `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
|
||||
- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
|
||||
|
||||
Use the latter for the "include" shortcode described above.
|
||||
|
||||
## Further explanation
|
||||
|
||||
To understand what is returned by the `RenderShortcodes` method, consider this content file
|
||||
|
||||
{{< code file=content/about.md lang=text >}}
|
||||
+++
|
||||
title = 'About'
|
||||
date = 2023-10-07T12:28:33-07:00
|
||||
+++
|
||||
|
||||
{{</* ref "privacy" */>}}
|
||||
|
||||
An *emphasized* word.
|
||||
{{< /code >}}
|
||||
|
||||
With this template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $p := site.GetPage "/about" }}
|
||||
{{ $p.RenderShortcodes }}
|
||||
```
|
||||
|
||||
Hugo renders this:;
|
||||
|
||||
```html
|
||||
https://example.org/privacy/
|
||||
|
||||
An *emphasized* word.
|
||||
```
|
||||
|
||||
Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user