Scratch doc: Use the special $ variable to prevent confusion

diff --git a/docs/content/extras/scratch.md b/docs/content/extras/scratch.md
index 9adef3a5a54c0e010d106108fdd511c2fb53b983..578b1c35401e2a1f8dcf3242c10be74a10d31388 100644 (file)
--- a/docs/content/extras/scratch.md
+++ b/docs/content/extras/scratch.md
@@ -25,18 +25,20 @@ The scope of the backing data is global for the given `Node` or `Page`, and span
 The usage is best illustrated with some samples:
 
 ```
-{{ .Scratch.Add "a1" 12 }}
-{{ .Scratch.Get "a1" }} {{/* => 12 */}}
-{{ .Scratch.Add "a1" 1 }}
-{{ .Scratch.Get "a1" }} // {{/* => 13 */}}
-
-{{ .Scratch.Add "a2" "AB" }}
-{{ .Scratch.Get "a2" }} {{/* => AB */}}
-{{ .Scratch.Add "a2" "CD" }}
-{{ .Scratch.Get "a2" }} {{/* => ABCD */}}
-
-{{ .Scratch.Set "v1" 123 }}
-{{ .Scratch.Get "v1" }}  {{/* => 123 */}}       
+{{ $.Scratch.Add "a1" 12 }}
+{{ $.Scratch.Get "a1" }} {{/* => 12 */}}
+{{ $.Scratch.Add "a1" 1 }}
+{{ $.Scratch.Get "a1" }} // {{/* => 13 */}}
+
+{{ $.Scratch.Add "a2" "AB" }}
+{{ $.Scratch.Get "a2" }} {{/* => AB */}}
+{{ $.Scratch.Add "a2" "CD" }}
+{{ $.Scratch.Get "a2" }} {{/* => ABCD */}}
+
+{{ $.Scratch.Set "v1" 123 }}
+{{ $.Scratch.Get "v1" }}  {{/* => 123 */}}
 ```
 
+**Note:** The examples above uses the special `$` variable, which refers to the top-level node. This is the behavior you most likely want, and will help remove some confusion when using `Scratch` inside page range loops -- and you start inadvertently calling the wrong `Scratch`. But there may be use cases for `{{ .Scratch.Add "key" "some value" }}`.
+