From 9f79bacc41857b6b62d35b18129583de6f0c8e49 Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Sat, 1 Nov 2025 11:15:37 -0700
Subject: [PATCH] content: Describe valid uses of the nil keyword

Closes #3250

Co-authored-by: Ruoyu Zhong <zhongruoyu@outlook.com>
---
 content/en/functions/compare/Default.md |  2 +-
 content/en/templates/introduction.md    | 31 +++++++++++++++++++++----
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md
index f8bd06f06..5925f7750 100644
--- a/content/en/functions/compare/Default.md
+++ b/content/en/functions/compare/Default.md
@@ -41,7 +41,7 @@ The `default` function returns the first argument if the second argument is not
 {{ default 42 "" }} → 42
 {{ default 42 dict }} → 42
 {{ default 42 slice }} → 42
-{{ default 42 <nil> }} → 42
+{{ default 42 nil }} → 42
 ```
 
 [`or`]: /functions/go-template/or/
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
index 26928420d..724ceb57c 100644
--- a/content/en/templates/introduction.md
+++ b/content/en/templates/introduction.md
@@ -90,9 +90,9 @@ Hugo renders this to:
 
 ## Actions
 
-In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
+In the examples above, the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
 
-A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), variables, functions, and methods.
+A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), the [current context](#current-context), [variables](#variables), [functions](#functions), [methods](#methods), and the [`nil`](#nil) keyword.
 
 ```go-html-template {file="layouts/page.html"}
 {{ $convertToLower := true }}
@@ -105,8 +105,10 @@ In the example above:
 
 - `$convertToLower` is a variable
 - `true` is a literal boolean value
+- `if` is the beginning of a control structure
 - `strings.ToLower` is a function that converts all characters to lowercase
 - `Title` is a method on a the `Page` object
+- `end` is the end of a control structure
 
 Hugo renders the above to:
 
@@ -185,6 +187,28 @@ This is line two.`
 }}
 ```
 
+### Nil
+
+Other than using the `nil` keyword in comparisons, you may not use it as an argument to any function or method, nor may you assign it to a variable. For example, these are valid uses of the `nil` keyword:
+
+```go-html-template
+{{ if gt 42 nil }}
+  <p>42 is greater than nil</p>
+{{ end }}
+
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+These, on the other hand, are invalid:
+
+```go-html-template
+{{ $a := nil }} 
+{{ add 3 nil }} 
+{{ nil | print}}
+```
+
+The actions above throw an error.
+
 ## Variables
 
 A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
@@ -517,10 +541,9 @@ In the template example above, each of the keys is a valid identifier. For examp
 [`template`]: /functions/go-template/template/
 [`Title`]: /methods/page/title
 [`with`]: /functions/go-template/with/
-[current context]: #current-context
 [embedded templates]: /templates/embedded/
-[front matter]: /content-management/front-matter/
 [front matter fields]: /content-management/front-matter/#fields
+[front matter]: /content-management/front-matter/
 [functions]: /functions/
 [go-templates]: /functions/go-template/
 [html/template]: https://pkg.go.dev/html/template