Add doc for Scratch

diff --git a/docs/content/extras/pagination.md b/docs/content/extras/pagination.md
index 2b121b2ee5afd2b5a36d135dc0851ddf469f3b4a..95c915b581e25fdfe83ffbd16f3c94b17850eeca 100644 (file)
--- a/docs/content/extras/pagination.md
+++ b/docs/content/extras/pagination.md
@@ -5,7 +5,7 @@ date: 2014-01-01
 menu:
   main:
     parent: extras
-next: /extras/highlighting
+next: /extras/scratch
 prev: /extras/shortcodes
 title: Pagination
 weight: 80

diff --git a/docs/content/extras/scratch.md b/docs/content/extras/scratch.md
new file mode 100644 (file)
index 0000000..9adef3a
--- /dev/null
+++ b/docs/content/extras/scratch.md
@@ -0,0 +1,42 @@
+---
+aliases:
+- /doc/scratch/
+date: 2015-01-22
+menu:
+  main:
+    parent: extras
+next: /extras/highlighting
+prev: /extras/pagination
+title: Scratch
+weight: 80
+---
+
+`Scratch` -- a "scratchpad" for your node- or page-scoped variables. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
+
+
+`Scratch` is added to both `Node` and `Page` -- with the three methods `Set`, `Get` and `Add`. `Set` and `Add` takes a `key` and the `value` to add. Get returns the `value` for the `key` given.
+
+`Set` can store values of any type. `Add` accepts values that support Go's `+` operator.
+
+The scope of the backing data is global for the given `Node` or `Page`, and spans partial and shortcode includes.
+
+## Sample usage
+
+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 */}}       
+```
+
+

diff --git a/docs/content/meta/release-notes.md b/docs/content/meta/release-notes.md
index 69a22e2968752bfec51ee87b8003d7534da8e570..17ef93c8f2ae6075717690a55014b8b193cea854 100644 (file)
--- a/docs/content/meta/release-notes.md
+++ b/docs/content/meta/release-notes.md
@@ -41,6 +41,7 @@ A lot has happened since Hugo v0.12.0 was released.
        * `GroupByParamDate(key, format, order)`
 * The [shortcode](/extras/shortcodes/) handling is rewritten for speed and better error messages. Noticeable functional change is the distinction between `{{</* */>}}` (typically raw HTML) and `{{%/* */%}}` (Markdown)
 * Support for [cross-references](/extras/crossreferences/)
+* `Scratch` -- [a "scratchpad"](/extras/scratch) for your node- and page-scoped variables
 * A new, generic Next/Prev functionality is added to all lists of pages (sections, taxonomies, etc.)
 * Add in-section [Next/Prev](/templates/variables/) content pointers
 * Several [configurable improvements related to Markdown rendering](/overview/configuration/#configure-blackfriday-rendering:a66b35d20295cb764719ac8bd35837ec):

diff --git a/docs/content/templates/variables.md b/docs/content/templates/variables.md
index db6268c3e9613e66edccfbc023f655608142ee05..75764e80b7b37af318dd8037acae39599326ac22 100644 (file)
--- a/docs/content/templates/variables.md
+++ b/docs/content/templates/variables.md
@@ -22,6 +22,8 @@ The following is a list of most of the accessible variables which can be
 defined for a piece of content. Many of these will be defined in the front
 matter, content or derived from file location.
 
+**See also:** [Scratch](/extras/scratch) for page-scoped writable variables.
+
 **.Title**  The title for the content.<br>
 **.Content** The content itself, defined below the front matter.<br>
 **.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page.  See [Summaries](/content/summaries/) for more details.<br>
@@ -65,6 +67,8 @@ Take for example I'm using *tags* and *categories* as my taxonomies. The followi
 In Hugo, a node is any page not rendered directly by a content file. This
 includes taxonomies, lists and the homepage.
 
+**See also:** [Scratch](/extras/scratch) for global node variables.
+
 **.Title**  The title for the content.<br>
 **.Date** The date the content is published on.<br>
 **.Permalink** The Permanent link for this node<br>