From a3184764d7666cd9ef95040f7fef3a6d97a85c70 Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Thu, 8 Feb 2024 22:42:31 -0800
Subject: [PATCH] Provide examples of content rendering before accessing
 Scratch or Store

Closes #2402
---
 content/en/content-management/diagrams.md |  2 +-
 content/en/methods/page/Scratch.md        | 19 +++++++++++++++++++
 content/en/methods/page/Store.md          | 19 +++++++++++++++++++
 content/en/render-hooks/code-blocks.md    |  2 +-
 content/en/troubleshooting/faq.md         | 16 ++++++++++++++++
 5 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md
index 2951dd8b2..ad9f5580c 100644
--- a/content/en/content-management/diagrams.md
+++ b/content/en/content-management/diagrams.md
@@ -58,7 +58,7 @@ Hugo does not provide a built-in template for Mermaid diagrams. Create your own
 And then include this snippet at the bottom of the content template:
 
 ```go-html-template
-{{ if .Page.Store.Get "hasMermaid" }}
+{{ if .Store.Get "hasMermaid" }}
   <script type="module">
     import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
     mermaid.initialize({ startOnLoad: true });
diff --git a/content/en/methods/page/Scratch.md b/content/en/methods/page/Scratch.md
index ba5eaa8f9..527e91095 100644
--- a/content/en/methods/page/Scratch.md
+++ b/content/en/methods/page/Scratch.md
@@ -9,6 +9,7 @@ action:
     - functions/collections/NewScratch
   returnType: maps.Scratch
   signatures: [PAGE.Scratch]
+toc: true
 aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
 ---
 
@@ -21,3 +22,21 @@ To create a locally scoped scratch pad that is not attached to a `Page` object,
 [scratch pad]: /getting-started/glossary/#scratch-pad
 
 {{% include "methods/page/_common/scratch-methods.md" %}}
+
+## Determinate values
+
+The `Scratch` 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 not determinate 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:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/content/en/methods/page/Store.md b/content/en/methods/page/Store.md
index 763c57f58..f9b5168c8 100644
--- a/content/en/methods/page/Store.md
+++ b/content/en/methods/page/Store.md
@@ -9,6 +9,7 @@ action:
   - functions/collections/NewScratch
   returnType: maps.Scratch
   signatures: [PAGE.Store]
+toc: true
 aliases: [/functions/store]
 ---
 
@@ -102,3 +103,21 @@ Removes the given key.
 {{ .Store.Set "greeting" "Hello" }}
 {{ .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 not determinate 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:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md
index b52f8802c..22295ac0a 100755
--- a/content/en/render-hooks/code-blocks.md
+++ b/content/en/render-hooks/code-blocks.md
@@ -122,7 +122,7 @@ For example, to create a code block render hook to render [Mermaid] diagrams:
 Then include this snippet at the bottom of the your base template:
 
 {{< code file=layouts/_default/baseof.html copy=true >}}
-{{ if .Page.Store.Get "hasMermaid" }}
+{{ if .Store.Get "hasMermaid" }}
   <script type="module">
     import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
     mermaid.initialize({ startOnLoad: true });
diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md
index cf054e897..f28936439 100644
--- a/content/en/troubleshooting/faq.md
+++ b/content/en/troubleshooting/faq.md
@@ -104,6 +104,22 @@ In its default configuration, Hugo's file watcher may not be able detect file ch
 
 In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds ms, use `--poll 700ms`.
 
+###### Why is my page Scratch or Store missing a value?
+
+The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a "scratch pad" on the given page to store and manipulate data. Values are often set 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 not determinate 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:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can trigger content rendering with other methods as well. See next FAQ.
+
+[`Scratch`]: /methods/page/scratch
+[`Store`]: /methods/page/store
+
 ###### Which page methods trigger content rendering?
 
 The following methods on a `Page` object trigger content rendering: `Content`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.