From 02c9e11c8bc77b95e96611ec72fe118658b421c6 Mon Sep 17 00:00:00 2001
From: Dave Henderson <dhenderson@gmail.com>
Date: Fri, 15 May 2020 21:03:09 -0400
Subject: Document variable scope

Signed-off-by: Dave Henderson <dhenderson@gmail.com>
---
 docs/content/syntax.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

(limited to 'docs')

diff --git a/docs/content/syntax.md b/docs/content/syntax.md
index 0bcaf54f..53c1e32b 100644
--- a/docs/content/syntax.md
+++ b/docs/content/syntax.md
@@ -126,6 +126,50 @@ Hello, world!
 Goodbye, world.
 ```
 
+Variables are declared with `:=`, and can be redefined with `=`:
+
+```
+{{ $w := "hello" }}
+{{ $w = "goodbye" }}
+```
+
+### Variable scope
+
+A variable's scope extends to the `end` action of the control structure (`if`,
+`with`, or `range`) in which it is declared, or to the end of the template if
+there is no such control structure.
+
+In other words, if a variable is initialized inside an `if` or `else` block,
+it cannot be referenced outside that block.
+
+This template will error with `undefined variable "$w"` since `$w` is only
+declared within `if`/`else` blocks:
+
+```
+{{ if 1 }}
+{{ $w := "world" }}
+{{ else }}
+{{ $w := "earth" }}
+{{ end }}
+
+Hello, {{ print $w }}!
+Goodbye, {{ print $w }}.
+```
+
+One way to approach this is to declare the variable first to an empty value:
+
+```
+{{ $w := "" }}
+{{ if 1 }}
+{{ $w = "world" }}
+{{ else }}
+{{ $w = "earth" }}
+{{ end -}}
+
+Hello, {{ print $w }}!
+Goodbye, {{ print $w }}.
+```
+
 ## Indexing arrays and maps
 
 Occasionally, multi-dimensional data such as arrays (lists, slices) and maps
-- 
cgit v1.2.3