Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb'

23 files changed, 728 insertions, 665 deletions

diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md
index 7cb6357c6..e87749d3a 100644
--- a/docs/content/en/content-management/_index.md
+++ b/docs/content/en/content-management/_index.md
@@ -8,7 +8,6 @@ menu:
     weight: 10
 keywords: [source, organization]
 categories: [content management]
-toc: false
 weight: 10
 aliases: [/content/,/content/organization]
 ---
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md
index 1d2ba3179..f2bc6a441 100644
--- a/docs/content/en/content-management/archetypes.md
+++ b/docs/content/en/content-management/archetypes.md
@@ -1,6 +1,5 @@
 ---
 title: Archetypes
-linkTitle: Archetypes
 description: Archetypes are templates used when creating new content.
 keywords: [archetypes,generators,metadata,front matter]
 categories: [content management]
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md
index f798754f1..4798f9b2b 100644
--- a/docs/content/en/content-management/build-options.md
+++ b/docs/content/en/content-management/build-options.md
@@ -56,43 +56,39 @@ If true, the page will be treated as part of the project's collections and, when
 
 #### publishResources
 
-If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published.
+If set to true the [Bundle's Resources](/content-management/page-bundles) will be published.
 Setting this to false will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others.
 
 {{% note %}}
-Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods.
+Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods.
 {{% /note %}}
 
-------
-
 ### Illustrative use cases
 
 #### Not publishing a page
 
 Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else.
 
-```yaml
-# content/who-we-are.md`
+{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}}
 title: Who we are
 _build:
  list: false
  render: false
-```
+{{< /code-toggle >}}
 
-```go-html-template
-{{/* layouts/index.html */}}
+{{< code file="layouts/index.html" copy=false >}}
 <section id="who-we-are">
-{{ with site.GetPage "who-we-are" }}
-  {{ .Content }}
-{{ end }}
+  {{ with site.GetPage "who-we-are" }}
+    {{ .Content }}
+  {{ end }}
 </section>
-```
+{{< /code >}}
 
 #### Listing pages without publishing them
 
 Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them.
 
-To avoid setting the build options on every testimonials, one can use [`cascade`]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file.
+To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file.
 
 {{< code-toggle >}}
 title: Testimonials
@@ -104,12 +100,12 @@ cascade:
     list: true # default
 {{< /code-toggle >}}
 
-```go-html-template
-{{/* layouts/_defaults/testimonials.html */}}
+{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
 <section id="testimonials">
-{{ range first 5 .Pages }}
-  <blockquote cite="{{ .Params.cite }}">
-    {{ .Content }}
-  </blockquote>
-{{ end }}
+  {{ range first 5 .Pages }}
+    <blockquote cite="{{ .Params.cite }}">
+      {{ .Content }}
+    </blockquote>
+  {{ end }}
 </section>
+{{< /code >}}
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index e49711e7c..0543f47a7 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -1,6 +1,5 @@
 ---
 title: Comments
-linkTitle: Comments
 description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
 keywords: [sections,content,organization]
 categories: [project organization, fundamentals]
@@ -25,7 +24,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
 
 Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
 
-{{< code-toggle copy="false" >}}
+{{< code-toggle copy=false >}}
 disqusShortname = "yourDisqusShortname"
 {{</ code-toggle >}}
 
diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md
index c95548249..e664dd501 100644
--- a/docs/content/en/content-management/diagrams.md
+++ b/docs/content/en/content-management/diagrams.md
@@ -1,6 +1,5 @@
 ---
 title: Diagrams
-LinkTitle: Diagrams
 description: Use fenced code blocks and markdown render hooks to display diagrams.
 categories: [content management]
 keywords: [diagrams,drawing]
@@ -58,8 +57,8 @@ And then include this snippet at the bottom of the content template (**Note**: b
 
 ```go-html-template
 {{ if .Page.Store.Get "hasMermaid" }}
-  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
-  <script>
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
     mermaid.initialize({ startOnLoad: true });
   </script>
 {{ end }}
@@ -67,6 +66,7 @@ And then include this snippet at the bottom of the content template (**Note**: b
 
 With that you can use the `mermaid` language in Markdown code blocks:
 
+````
 ```mermaid
 sequenceDiagram
     participant Alice
@@ -80,6 +80,7 @@ sequenceDiagram
     John->>Bob: How about you?
     Bob-->>John: Jolly good!
 ```
+````
 
 ## Goat Ascii Diagram Examples
 
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
index a98898821..ba988c29b 100644
--- a/docs/content/en/content-management/formats.md
+++ b/docs/content/en/content-management/formats.md
@@ -46,9 +46,9 @@ Hugo passes reasonable default arguments to these external helpers by default:
 - `rst2html`: `--leave-comments --initial-header-level=2`
 - `pandoc`: `--mathjax`
 
-{{% warning "Performance of External Helpers" %}}
+{{% note %}}
 Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
-{{% /warning %}}
+{{% /note %}}
 
 ### External Helper AsciiDoc
 
diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md
index bf530518f..78d3323dd 100644
--- a/docs/content/en/content-management/front-matter.md
+++ b/docs/content/en/content-management/front-matter.md
@@ -1,8 +1,6 @@
 ---
 title: Front Matter
-linkTitle: Front Matter
 description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
-lastmod: 2017-02-24
 categories: [content management]
 keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
 menu:
@@ -56,87 +54,87 @@ slug = "spf13-vim-3-0-release-and-new-website"
 There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
 
 aliases
-: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
 
 audio
-: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
+: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
 
 cascade
-: a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
+: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
 
 date
-: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
+: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
 
 description
-: the description for the content.
+: The description for the content.
 
 draft
-: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
 
 expiryDate
-: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
 
 headless
-: if `true`, sets a leaf bundle to be [headless][headless-bundle].
+: If `true`, sets a leaf bundle to be [headless][headless-bundle].
 
 images
-: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
+: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
 
 isCJKLanguage
-: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
 
 keywords
-: the meta keywords for the content.
+: The meta keywords for the content.
 
 layout
-: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
+: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
 
 lastmod
-: the datetime at which the content was last modified.
+: The datetime at which the content was last modified.
 
 linkTitle
-: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
+: Used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
 
 markup
 : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
 
 outputs
-: allows you to specify output formats specific to the content. See [output formats][outputs].
+: Allows you to specify output formats specific to the content. See [output formats][outputs].
 
 publishDate
-: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
 
 resources
-: used for configuring page bundle resources. See [Page Resources][page-resources].
+: Used for configuring page bundle resources. See [Page Resources][page-resources].
 
 series
-: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
+: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
 
 slug
-: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
+: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
 
 summary
-: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
 
 title
-: the title for the content.
+: The title for the content.
 
 type
-: the type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
+: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
 
 url
-: the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
+: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
 
 videos
-: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
+: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
 
 weight
 : used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
 
 \<taxonomies\>
-: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
+: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
 
-{{% note "Hugo's Default URL Destinations" %}}
+{{% note %}}
 If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
 {{% /note %}}
 
@@ -146,7 +144,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us
 
 The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
 
-{{< code-toggle copy="false" >}}
+{{< code-toggle copy=false >}}
 include_toc: true
 show_comments: false
 {{</ code-toggle >}}
@@ -159,7 +157,7 @@ Any node or section can pass down to descendants a set of Front Matter values as
 
 The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
 
-{{< code-toggle copy="false" >}}
+{{< code-toggle copy=false >}}
 title ="Blog"
 [[cascade]]
 background = "yosemite.jpg"
@@ -193,7 +191,7 @@ Any of the above can be omitted.
 
 In `content/blog/_index.md`
 
-{{< code-toggle copy="false" >}}
+{{< code-toggle copy=false >}}
 title: Blog
 cascade:
   banner: images/typewriter.jpg
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md
index 3f71b4244..0043f97b0 100644
--- a/docs/content/en/content-management/image-processing/index.md
+++ b/docs/content/en/content-management/image-processing/index.md
@@ -1,6 +1,5 @@
 ---
 title: Image Processing
-linkTitle: Image Processing
 description: Resize, crop, rotate, filter, and convert images.
 categories: [content management]
 keywords: [resources, images]
@@ -457,15 +456,15 @@ If you change image processing methods or options, or if you rename or remove im
 hugo --gc
 ```
 
-[`anchor`]: {{< relref "content-management/image-processing#anchor" >}}
-[`lang.FormatNumber`]: {{< relref "functions/lang#langformatnumber" >}}
-[Exif]: <https://en.wikipedia.org/wiki/Exif>
-[filters]: {{< relref "functions/images" >}}
+[time.Format]: /functions/dateformat
+[`anchor`]: /content-management/image-processing#anchor
+[mounted]: /hugo-modules/configuration#module-config-mounts
+[page bundle]: /content-management/page-bundles
+[`lang.FormatNumber`]: /functions/lang
+[filters]: /functions/images
 [github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
-[mounted]: {{< relref "hugo-modules/configuration#module-config-mounts">}}
-[page bundle]: {{< relref "content-management/page-bundles" >}}
 [Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
-[time.Format]: {{< relref "functions/dateformat" >}}
+[Exif]: <https://en.wikipedia.org/wiki/Exif>
 [`Colors`]: #colors
 [`Crop`]: #crop
 [`Exif`]: #exif
diff --git a/docs/content/en/content-management/menus.md b/docs/content/en/content-management/menus.md
index b9fab2ca4..369938aba 100644
--- a/docs/content/en/content-management/menus.md
+++ b/docs/content/en/content-management/menus.md
@@ -1,7 +1,6 @@
 ---
 title: Menus
-linkTitle: Menus
-description: Hugo has a simple yet powerful menu system.
+description:  Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
 categories: [content management]
 keywords: [menus]
 menu:
@@ -13,117 +12,214 @@ weight: 190
 aliases: [/extras/menus/]
 ---
 
-{{% note "Lazy Blogger"%}}
-If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers).
-{{% /note %}}
+## Overview
+
+To create a menu for your site:
 
-You can do this:
+1. Define the menu entries
+2. [Localize] each entry
+3. Render the menu with a [template]
 
-* Place content in one or many menus
-* Handle nested menus with unlimited depth
-* Create menu entries without being attached to any content
-* Distinguish active element (and active branch)
+Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
 
-## What is a Menu in Hugo?
+There are three ways to define menu entries:
 
-A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
+1. Automatically
+1. In front matter
+1. In site configuration
 
-{{% note "Menus on Multilingual Sites" %}}
-If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
+{{% note %}}
+Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
 {{% /note %}}
 
-See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry.
+## Define automatically
 
-## Add content to menus
+To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
 
-Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
+{{< code-toggle file="config" copy=false >}}
+sectionPagesMenu = "main"
+{{< /code-toggle >}}
 
-### Simple
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
 
-If all you need to do is add an entry to a menu, the simple form works well.
+## Define in front matter
 
-#### A Single Menu
+To add a page to the "main" menu:
 
-{{< code-toggle >}}
-menu: "main"
+{{< code-toggle file="content/about.md" copy=false fm=true >}}
+title = 'About'
+menu = 'main'
 {{< /code-toggle >}}
 
-#### Multiple Menus
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+To add a page to the "main" and "footer" menus:
 
-{{< code-toggle >}}
-menu: ["main", "footer"]
+{{< code-toggle file="content/contact.md" copy=false fm=true >}}
+title = 'Contact'
+menu = ['main','footer']
 {{< /code-toggle >}}
 
-#### Advanced
+Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
 
-{{< code-toggle >}}
-menu:
-  docs:
-    parent: 'extras'
-    weight: 20
+### Properties {#properties-front-matter}
+
+Use these properties when defining menu entries in front matter:
+
+identifier
+: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
+
+name
+: (`string`) The text to display when rendering the menu entry.
+
+params
+: (`map`) User-defined properties for the menu entry.
+
+parent
+: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
+
+post
+: (`string`) The HTML to append when rendering the menu entry.
+
+pre
+: (`string`) The HTML to prepend when rendering the menu entry.
+
+title
+: (`string`) The HTML `title` attribute of the rendered menu entry.
+
+weight
+: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
+
+### Example {#example-front-matter}
+
+This front matter menu entry demonstrates some of the available properties:
+
+{{< code-toggle file="content/products/software.md" copy=false fm=true >}}
+title = 'Software'
+[menu.main]
+parent = 'Products'
+weight = 20
+pre = '<i class="fa-solid fa-code"></i>'
+[menu.main.params]
+class = 'center'
 {{< /code-toggle >}}
 
-## Add Non-content Entries to a Menu
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
 
-You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config] (see [Menu Entry Properties][me-props] for full details of available variables).
+## Define in site configuration
 
-Here’s an example snippet pulled from a configuration file:
+To define entries for the "main" menu:
 
-{{< code-toggle file="config" >}}
+{{< code-toggle file="config" copy=false >}}
 [[menu.main]]
-    name = "about hugo"
-    pre = "<i class='fa fa-heart'></i>"
-    weight = -110
-    identifier = "about"
-    url = "/about/"
+name = 'Home'
+pageRef = '/'
+weight = 10
+
 [[menu.main]]
-    name = "getting started"
-    pre = "<i class='fa fa-road'></i>"
-    post = "<span class='alert'>New!</span>"
-    weight = -100
-    url = "/getting-started/"
+name = '