tpl/transform: Add transform.XMLEscape template function

Fixes #3268

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/content/en/functions/transform/XMLEscape.md b/docs/content/en/functions/transform/XMLEscape.md
new file mode 100644
index 000000000..17ed2a13d
--- /dev/null
+++ b/docs/content/en/functions/transform/XMLEscape.md
@@ -0,0 +1,38 @@
+---
+title: transform.XMLEscape
+description: Returns the given string, removing disallowed characters then escaping the result to its XML equivalent.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related: []
+  returnType: string
+  signatures: [transform.XMLEscape INPUT]
+---
+
+The `transform.XMLEscape` function removes [disallowed characters] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+
+- `"` → `"`
+- `'` → `'`
+- `&` → `&`
+- `<` → `&lt;`
+- `>` → `&gt;`
+- `\t` → `&#x9;`
+- `\n` → `&#xA;`
+- `\r` → `&#xD;`
+
+For example:
+
+```go-html-template
+transform.XMLEscape "<p>abc</p>" → &lt;p&gt;abc&lt;/p&gt;
+```
+
+When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
+
+{{< code file="layouts/_default/rss.xml" >}}
+<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+{{< /code >}}
+
+[disallowed characters]: https://www.w3.org/TR/xml/#charsets
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
+[html/template]: https://pkg.go.dev/html/template