Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

docs/content/en/methods/menu/ByName.md

@@ -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 >}}
+[[menu.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menu.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menu.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

docs/content/en/methods/menu/ByWeight.md

@@ -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 >}}
+[[menu.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menu.main]]
+identifier = 'services'
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menu.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

docs/content/en/methods/menu/Limit.md

@@ -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 >}}
+[[menu.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menu.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menu.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>
+```

docs/content/en/methods/menu/Reverse.md

@@ -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 >}}
+[[menu.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menu.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menu.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>
+```

docs/content/en/methods/menu/_index.md

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