Add SafeJS template function

This commit adds a SafeJS template function.  Tests and documentation are
included.

Fixes #1579

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md
index fc6c361e6..503702290 100644
--- a/docs/content/templates/functions.md
+++ b/docs/content/templates/functions.md
@@ -456,6 +456,21 @@ Example: Given `style = "color: red;"` defined in the front matter of your `.md`
 Note: "ZgotmplZ" is a special value that indicates that unsafe content reached a
 CSS or URL context.
 
+### safeJS
+
+Declares the provided string as a known "safe" Javascript string so Go
+html/templates will not escape it.  "Safe" means the string encapsulates a known
+safe EcmaScript5 Expression, for example, `(x + y * z())`. Template authors
+are responsible for ensuring that typed expressions do not break the intended
+precedence and that there is no statement/expression ambiguity as when passing
+an expression like `{ foo:bar() }\n['foo']()`, which is both a valid Expression
+and a valid Program with a very different meaning.
+
+Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file:
+
+* `<script>var form_{{ .Params.hash | safeJS }};…</script>` ⇒ `<script>var form_619c16f;…</script>` (Good!)
+* `<script>var form_{{ .Params.hash }};…</script>` ⇒ `<script>var form_"619c16f";…</script>` (Bad!)
+
 ### singularize
 Singularize the given word with a set of common English singularization rules.