Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs'

```
git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash
```

Closes #11925

docs/content/en/functions/safe/CSS.md

@@ -0,0 +1,33 @@
+---
+title: safe.CSS
+description: Declares the given string as safe CSS string.
+categories: []
+keywords: []
+action:
+  aliases: [safeCSS]
+  related:
+    - functions/safe/HTML
+    - functions/safe/HTMLAttr
+    - functions/safe/JS
+    - functions/safe/JSStr
+    - functions/safe/URL
+  returnType: template.CSS
+  signatures: [safe.CSS INPUT]
+aliases: [/functions/safecss]
+---
+
+In this context, *safe* means CSS content that matches any of the following:
+
+1. The CSS3 stylesheet production, such as `p { color: purple }`.
+2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+3. CSS3 declaration productions, such as `color: red; margin: 2px`.
+4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+
+Example: Given `style = "color: red;"` defined in the front matter of your `.md` file:
+
+* `<p style="{{ .Params.style | safeCSS }}">…</p>` &rarr; `<p style="color: red;">…</p>`
+* `<p style="{{ .Params.style }}">…</p>` &rarr; `<p style="ZgotmplZ">…</p>`
+
+{{% note %}}
+`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context.
+{{% /note %}}

docs/content/en/functions/safe/HTML.md

@@ -0,0 +1,39 @@
+---
+title: safe.HTML
+description: Declares the given string as a safeHTML string.
+categories: []
+keywords: []
+action:
+  aliases: [safeHTML]
+  related:
+    - functions/safe/CSS
+    - functions/safe/HTMLAttr
+    - functions/safe/JS
+    - functions/safe/JSStr
+    - functions/safe/URL
+  returnType: template.HTML
+  signatures: [safe.HTML INPUT]
+aliases: [/functions/safehtml]
+---
+
+It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
+
+Given a site-wide [`hugo.toml`][config] with the following `copyright` value:
+
+{{< code-toggle file=hugo >}}
+copyright = "© 2015 Jane Doe.  <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>."
+{{< /code-toggle >}}
+
+`{{ .Site.Copyright | safeHTML }}` in a template would then output:
+
+```html
+© 2015 Jane Doe.  <a href="https://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
+```
+
+However, without the `safeHTML` function, html/template assumes `.Site.Copyright` to be unsafe and therefore escapes all HTML tags and renders the whole string as plain text:
+
+```html
+<p>© 2015 Jane Doe.  &lt;a href=&#34;https://creativecommons.org/licenses by/4.0/&#34;&gt;Some rights reserved&lt;/a&gt;.</p>
+```
+
+[config]: /getting-started/configuration/

docs/content/en/functions/safe/HTMLAttr.md

@@ -0,0 +1,55 @@
+---
+title: safe.HTMLAttr
+description: Declares the given key/value pair as a safe HTML attribute.
+categories: []
+keywords: []
+action:
+  aliases: [safeHTMLAttr]
+  related:
+    - functions/safe/CSS
+    - functions/safe/HTML
+    - functions/safe/JS
+    - functions/safe/JSStr
+    - functions/safe/URL
+  returnType: template.HTMLAttr
+  signatures: [safe.HTMLAttr INPUT]
+aliases: [/functions/safehtmlattr]
+---
+
+Given a site configuration that contains this menu entry:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+  name = "IRC"
+  url = "irc://irc.freenode.net/#golang"
+{{< /code-toggle >}}
+
+Attempting to use the `url` value directly in an attribute:
+
+```go-html-template
+{{ range site.Menus.main }}
+  <a href="{{ .URL }}">{{ .Name }}</a>
+{{ end }}
+```
+
+Will produce:
+
+```html
+<a href="#ZgotmplZ">IRC</a>
+```
+
+`ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
+
+To indicate that the HTML attribute is safe:
+
+```go-html-template
+{{ range site.Menus.main }}
+  <a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
+{{ end }}
+```
+
+{{% note %}}
+As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect.
+{{% /note %}}
+
+[template/html]: https://pkg.go.dev/html/template

docs/content/en/functions/safe/JS.md

@@ -0,0 +1,26 @@
+---
+title: safe.JS
+description: Declares the given string as a safe JavaScript expression.
+categories: []
+keywords: []
+action:
+  aliases: [safeJS]
+  related:
+    - functions/safe/CSS
+    - functions/safe/HTML
+    - functions/safe/HTMLAttr
+    - functions/safe/JSStr
+    - functions/safe/URL
+  returnType: template.JS
+  signatures: [safe.JS INPUT]
+aliases: [/functions/safejs]
+---
+
+In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(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>` &rarr; `<script>var form_619c16f;…</script>`
+* `<script>var form_{{ .Params.hash }};…</script>` &rarr; `<script>var form_"619c16f";…</script>`

docs/content/en/functions/safe/JSStr.md

@@ -0,0 +1,55 @@
+---
+title: safe.JSStr
+description: Declares the given string as a safe JavaScript string.
+categories: []
+keywords: []
+action:
+  aliases: [safeJSStr]
+  related:
+    - functions/safe/CSS
+    - functions/safe/HTML
+    - functions/safe/HTMLAttr
+    - functions/safe/JS
+    - functions/safe/URL
+  returnType: template.JSStr
+  signatures: [safe.JSStr INPUT]
+aliases: [/functions/safejsstr]
+---
+
+Encapsulates a sequence of characters meant to be embedded between quotes in a JavaScript expression. Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+  
+Without declaring a variable to be a safe JavaScript string:
+
+```go-html-template
+{{ $title := "Lilo & Stitch" }}
+<script>
+  const a = "Title: " + {{ $title }};
+</script>
+```
+
+Rendered:
+
+```html
+<script>
+  const a = "Title: " + "Lilo \u0026 Stitch";
+</script>
+```
+
+To avoid escaping by Go's [html/template] package:
+
+```go-html-template
+{{ $title := "Lilo & Stitch" }}
+<script>
+  const a = "Title: " + {{ $title | safeJSStr }};
+</script>
+```
+
+Rendered:
+
+```html
+<script>
+  const a = "Title: " + "Lilo & Stitch";
+</script>
+```
+
+[html/template]: https://pkg.go.dev/html/template

docs/content/en/functions/safe/URL.md

@@ -0,0 +1,70 @@
+---
+title: safe.URL
+description: Declares the given string as a safe URL or URL substring.
+categories: []
+keywords: []
+action:
+  aliases: [safeURL]
+  related:
+    - functions/safe/CSS
+    - functions/safe/HTML
+    - functions/safe/HTMLAttr
+    - functions/safe/JS
+    - functions/safe/JSStr
+  returnType: template.URL
+  signatures: [safe.URL INPUT]
+aliases: [/functions/safeurl]
+---
+
+`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
+
+Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
+
+The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = "IRC: #golang at freenode"
+url = "irc://irc.freenode.net/#golang"
+{{< /code-toggle >}}
+
+The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
+
+{{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
+<!-- This unordered list may be part of a sidebar menu -->
+<ul>
+  {{ range .Site.Menus.main }}
+    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+  {{ end }}
+</ul>
+{{< /code >}}
+
+This partial would produce the following HTML output:
+
+```html
+<!-- This unordered list may be part of a sidebar menu -->
+<ul>
+  <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
+</ul>
+```
+
+The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
+
+{{< code file=layouts/partials/correct-url-sidebar-menu.html >}}
+<!-- This unordered list may be part of a sidebar menu -->
+<ul>
+    <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
+</ul>
+{{< /code >}}
+
+With the `.URL` page variable piped through `safeURL`, we get the desired output:
+
+```html
+<ul class="sidebar-menu">
+  <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
+</ul>
+```
+
+[configuration]: /getting-started/configuration/
+[menus]: /content-management/menus/
+[RFC 3986]: https://tools.ietf.org/html/rfc3986

docs/content/en/functions/safe/_index.md

@@ -0,0 +1,14 @@
+---
+title: Safe functions
+linkTitle: safe
+description: Template functions to declare a value as safe in the context of Go's html/template package.
+categories: []
+keywords: []
+menu:
+  docs:
+    parent: functions
+---
+
+Use these functions to declare a value as safe in the context of Go's [html/template] package.
+
+[html/template]: https://pkg.go.dev/html/template