Merge commit 'e477373487abcccdbed95688e37aa74b9b8fc198'

docs/content/en/methods/menu-entry/PageRef.md

@@ -0,0 +1,120 @@
+---
+title: PageRef
+description: Returns the `pageRef` property of the given menu entry.
+categories: []
+keywords: []
+action:
+  related:
+    - /methods/menu-entry/URL
+  returnType: string
+  signatures: [MENUENTRY.PageRef]
+toc: true
+---
+
+The use case for this method is rare.
+
+In almost also scenarios you should use the [`URL`] method instead.
+
+## Explanation
+
+If you specify a `pageRef` property when [defining a menu entry] in your site configuration, Hugo looks for a matching page when rendering the entry.
+
+If a matching page is found:
+
+- The [`URL`] method returns the page's relative permalink
+- The [`Page`] method returns the corresponding `Page` object
+- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return the expected values
+
+If a matching page is not found:
+
+- The [`URL`] method returns the entry's `url` property if set, else an empty string
+- The [`Page`] method returns nil
+- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false`
+
+{{% note %}}
+In almost also scenarios you should use the [`URL`] method instead.
+
+[`URL`]: /methods/menu-entry/url/
+{{% /note %}}
+
+[defining a menu entry]: /content-management/menus/#define-in-site-configuration
+[`Page`]: /methods/menu-entry/page/
+[`URL`]: /methods/menu-entry/url/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`RelPermalink`]: /methods/page/relpermalink/
+
+## Example
+
+This example is contrived.
+
+{{% note %}}
+In almost also scenarios you should use the [`URL`] method instead.
+
+[`URL`]: /methods/menu-entry/url/
+{{% /note %}}
+
+
+Consider this content structure:
+
+```text
+content/
+├── products.md
+└── _index.md
+```
+
+And this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+With this template code:
+
+{{< code file=layouts/partials/menu.html >}}
+<ul>
+  {{ range .Site.Menus.main }}
+    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+  {{ end }}
+</ul>
+{{< /code >}}
+
+Hugo render this HTML:
+
+```html
+<ul>
+  <li><a href="/products/">Products</a></li>
+  <li><a href="">Services</a></li>
+</ul>
+```
+
+In the above note that the `href` attribute of the second `anchor` element is blank because Hugo was unable to find the "services" page.
+
+With this template code:
+
+
+{{< code file=layouts/partials/menu.html >}}
+<ul>
+  {{ range .Site.Menus.main }}
+    <li><a href="{{ or .URL .PageRef }}">{{ .Name }}</a></li>
+  {{ end }}
+</ul>
+{{< /code >}}
+
+Hugo renders this HTML:
+
+```html
+<ul>
+  <li><a href="/products/">Products</a></li>
+  <li><a href="/services">Services</a></li>
+</ul>
+```
+
+In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in the site configuration because the template code falls back to the `PageRef` method.

docs/content/en/methods/menu-entry/_common/pre-post.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: 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:

docs/content/en/methods/page/Ancestors.md

@@ -16,8 +16,6 @@ action:
   signatures: [PAGE.Ancestors]
 ---
 
-{{< new-in 0.109.0 >}}
-
 {{% include "methods/page/_common/definition-of-section.md" %}}
 
 With this content structure:

docs/content/en/methods/page/GitInfo.md

@@ -141,6 +141,7 @@ Some providers perform deep clones by default, others allow you to configure the
 
 Hosting service | Default clone depth | Configurable
 :-- | :-- | :--
+AWS Amplify | Deep | N/A
 Cloudflare Pages | Shallow | Yes [^CFP]
 DigitalOcean App Platform | Deep | N/A
 GitHub Pages | Shallow | Yes [^GHP]

docs/content/en/methods/page/HasMenuCurrent.md

@@ -28,4 +28,8 @@ If the `Page` object associated with the menu entry is a section, this method al
 
 See [menu templates] for a complete example.
 
+{{% note %}}
+When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
+{{% /note %}}
+
 [menu templates]: /templates/menu/#example

docs/content/en/methods/page/IsMenuCurrent.md

@@ -26,4 +26,8 @@ aliases: [/functions/ismenucurrent]
 
 See [menu templates] for a complete example.
 
+{{% note %}}
+When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
+{{% /note %}}
+
 [menu templates]: /templates/menu/#example

docs/content/en/methods/page/Store.md

@@ -1,11 +1,14 @@
 ---
 title: Store
+linktitle: PAGE.Store
 description: Returns a persistent "scratch pad" on the given page to store and manipulate data.
 categories: []
 keywords: []
 action:
   related:
   - methods/page/scratch
+  - methods/site/store
+  - functions/hugo/store
   - functions/collections/NewScratch
   returnType: maps.Scratch
   signatures: [PAGE.Store]

docs/content/en/methods/page/_common/definition-of-section.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 A _section_ is a top-level content directory, or any content directory with an _index.md file.

docs/content/en/methods/page/_common/next-and-prev.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages according to this sorting hierarchy:

docs/content/en/methods/page/_common/nextinsection-and-previnsection.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages according to this sorting hierarchy:

docs/content/en/methods/page/_common/output-format-definition.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 Hugo generates one or more files per page when building a site. For example, when rendering home, [section], [taxonomy], and [term] pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind], or by enabling one or more output formats for one or more pages. See [details].
 

docs/content/en/methods/page/_common/output-format-methods.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 Get IDENTIFIER

docs/content/en/methods/page/_common/scratch-methods.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 ## Methods

docs/content/en/methods/pages/_common/group-sort-order.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 For the optional sort order, specify either `asc` for ascending order, or `desc` for descending order.

docs/content/en/methods/pages/_common/next-and-prev.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 Hugo determines the _next_ and _previous_ page by sorting the page collection according to this sorting hierarchy:

docs/content/en/methods/resource/_common/global-page-remote-resources.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 {{% note %}}

docs/content/en/methods/resource/_common/processing-spec.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 ## Process specification

docs/content/en/methods/shortcode/Ordinal.md

@@ -11,6 +11,10 @@ action:
 
 The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
 
+{{% note %}}
+Hugo  increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
+{{% /note %}}
+
 This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
 
 {{< code file=content/about.md lang=md >}}

docs/content/en/methods/shortcode/Scratch.md

@@ -10,7 +10,17 @@ action:
   signatures: [SHORTCODE.Scratch]
 ---
 
-The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode, and is reset on server rebuilds.
+{{% deprecated-in 0.139.0 %}}
+Use the [`SHORTCODE.Store`] method instead.
+
+This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible.
+
+Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`.
+
+[`SHORTCODE.Store`]: /methods/shortcode/store/
+{{% /deprecated-in %}}
+
+The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode.
 
 {{% note %}}
 With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete.

docs/content/en/methods/shortcode/Store.md

@@ -0,0 +1,29 @@
+---
+title: Store
+description: Returns a "Store pad" scoped to the shortcode to store and manipulate data. 
+categories: []
+keywords: []
+action:
+  related:
+    - functions/collections/NewScratch
+    - methods/page/Store
+    - methods/site/Store
+    - functions/hugo/Store
+  returnType: maps.Store
+  signatures: [SHORTCODE.Store]
+---
+
+{{< new-in 0.139.0 >}}
+
+The `Store` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode.
+
+{{% note %}}
+With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
+
+[assign values to template variables]: https://go.dev/doc/go1.11#text/template
+[`newScratch`]: /functions/collections/newScratch/
+{{% /note %}}
+
+[Store pad]: /getting-started/glossary/#scratch-pad
+
+{{% include "methods/page/_common/scratch-methods.md" %}}

docs/content/en/methods/site/Store.md

@@ -0,0 +1,126 @@
+---
+title: Store
+linktitle: site.Store
+description: Returns a persistent "scratch pad" on the given site to store and manipulate data.
+categories: []
+keywords: []
+action:
+  related:
+  - methods/page/store
+  - functions/hugo/store
+  - functions/collections/NewScratch
+  returnType: maps.Scratch
+  signatures: [site.Store]
+toc: true
+---
+
+{{< new-in 0.139.0 >}}
+
+The `Store` method on a `Site` object creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Site` object, use the [`newScratch`] function.
+
+[`Scratch`]: /methods/site/scratch/
+[`newScratch`]: /functions/collections/newscratch/
+[scratch pad]: /getting-started/glossary/#scratch-pad
+
+## Methods
+
+###### Set
+
+Sets the value of a given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+```
+
+###### Get
+
+Gets the value of a given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Get "greeting" }} → Hello
+```
+
+###### Add
+
+Adds a given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Add "greeting" "Welcome" }}
+{{ site.Store.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ site.Store.Set "total" 3 }}
+{{ site.Store.Add "total" 7 }}
+{{ site.Store.Get "total" }} → 10
+```
+
+```go-html-template
+{{ site.Store.Set "greetings" (slice "Hello") }}
+{{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ site.Store.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+###### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+###### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.DeleteInMap "greetings" "english" }}
+{{ site.Store.Get "greetings" }} → map[french:Bonjour]
+```
+
+###### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+###### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Delete "greeting" }}
+```
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ site.Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ site.Store.Get "mykey" }}
+```

docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object.

docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md

@@ -1,5 +1,5 @@
 ---
-# Do not remove front matter.
+_comment: Do not remove front matter.
 ---
 
 An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.