Add reference docs pages

site/routes_reference.go

@@ -22,9 +22,10 @@ func setupReferences(ctx context.Context, router chi.Router) error {
 			Links: []*SidebarLink{
 				{ID: "attribute_plugins"},
 				{ID: "action_plugins"},
-				{ID: "datastar_context"},
+				{ID: "expression_context"},
 				{ID: "sse_events"},
 				{ID: "sdks"},
+				{ID: "security"},
 			},
 		},
 	}
@@ -64,7 +65,7 @@ func setupReferences(ctx context.Context, router chi.Router) error {
 
 		// Redirect legacy “JavaScript APIs” page.
 		referenceRouter.Get("/javascript_api", func(w http.ResponseWriter, r *http.Request) {
-			http.Redirect(w, r, "/reference/datastar_context", http.StatusMovedPermanently)
+			http.Redirect(w, r, "/reference/expression_context", http.StatusMovedPermanently)
 		})
 
 		referenceRouter.Get("/{name}", func(w http.ResponseWriter, r *http.Request) {

site/static/md/guide/datastar_expressions.md

@@ -10,7 +10,7 @@ The following example outputs `1` not because `$foo` is defined in the global sc
 </div>
 ```
 
-When Datastar evaluates the expression `$foo`, it first converts it to `ctx.signals.signal('foo').value`, and then evaluates that expression in a sandboxed context, in which `ctx` represents the Datastar context. 
+When Datastar evaluates the expression `$foo`, it first converts it to `ctx.signals.signal('foo').value`, and then evaluates that expression in a sandboxed context, in which `ctx` represents the current [expression context](/reference/expression_context). 
 
 This means that JavaScript can be used in Datastar expressions.
 
@@ -66,4 +66,4 @@ Expressions may span multiple lines, but a semicolon must be used to separate st
 </div>
 ```
 
-See the [Datastar Context reference](/reference/datastar_context) for more advanced usage of Datastar expressions.
+See the [Expression Context reference](/reference/expression_context) for more advanced usage of Datastar expressions.

site/static/md/reference/attribute_plugins.md

@@ -421,7 +421,7 @@ The signal name can be specified in the key (as above), or in the value (as belo
 
 ### `data-star-ignore`
 
-Datastar walks the entire DOM and applies plugins to each element it encounters. It's possible to tell Datastar to ignore an element and its descendants by placing a `data-star-ignore` attribute on it. This can be useful for preventing naming conflicts with third-party libraries.
+Datastar walks the entire DOM and applies plugins to each element it encounters. It's possible to tell Datastar to ignore an element and its descendants by placing a `data-star-ignore` attribute on it. This can be useful for preventing naming conflicts with third-party libraries, or when you are unable to [escape user input](/reference/security#escape-user-input).
 
 ```html
 <div data-star-ignore data-show-thirdpartylib>

site/static/md/reference/expression_context.md

@@ -0,0 +1,31 @@
+# Expression Context
+
+Datastar is _not_ exposed in the global scope. Everything you need to do should be possible via Datastar expressions in [attribute plugins](/reference/attribute_plugins) and [`datastar-execute-script`](/reference/sse_events#datastar-execute-script) SSE events.
+
+Every Datastar expression is evaluated using a context `ctx`. This means that `ctx` is exposed in expressions and can be used to access properties and methods within the current context.
+
+You should use `ctx` sparingly, and only when you can't achieve the desired behavior using signals.
+
+### `ctx.el`
+
+The current element being processed.
+
+### `ctx.plugin`
+
+The current plugin being processed.
+
+### `ctx.signals`
+
+The signals root object that contains functions for accessing and modifying signals. Signals can be accessed using the `signal` method. The following is the equivalent of an expression containing only `$foo`.
+
+```html
+<div data-signals-foo="1">
+  <div data-text="ctx.signals.signal('foo').value"></div>
+</div>
+```
+
+Here is how you can output the existing signals in JSON format, which can be useful when troubleshooting an issue.
+
+```html
+<pre data-text="ctx.signals.JSON()"></pre>
+```

site/static/md/reference/security.md

@@ -0,0 +1,23 @@
+# Security
+
+[Datastar expressions](/guide/datastar_expressions) are strings that are evaluated in a sandboxed context, in which `ctx` represents the Datastar context. This means that JavaScript can be used in Datastar expressions. 
+
+## Escape User Input
+
+The first rule of security is to never trust user input. This is especially true when using Datastar expressions, which can execute arbitrary JavaScript. 
+
+When using Datastar expressions, you should always escape user input. This is to prevent, among other issues, Cross Site Scripting (XSS) attacks.
+
+## Ignore Unsafe Input
+
+If, for some reason, you cannot escape unsafe user input, you should ignore it using the [`data-star-ignore`](/reference/attribute_plugins#data-star-ignore) attribute. This tells Datastar to ignore an element and its descendants when processing DOM nodes.
+
+## Content Security Policy
+
+When using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP), `unsafe-eval` must be allowed for scripts, since Datastar evaluates expressions inline. 
+
+```html
+<meta http-equiv="Content-Security-Policy" 
+      content="script-src 'self' 'unsafe-eval';"
+>
+```