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
2024-01-27 10:48:33 +01:00
1158 changed files with 64103 additions and 0 deletions

View 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>
```

View 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>
```

View 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 %}}

View 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

View 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

View 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 pages [`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 pages `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>
```

View 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

View 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/

View 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>
```

View 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" %}}

View 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" %}}

View 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 pages [`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 pages `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>
```

View 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

View 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 pages [`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 pages `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>
```

View 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.
-->

View 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/

View 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.