Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'

2025-08-21 21:35:28 +02:00 · 2023-10-20 09:43:56 +02:00
parent fd38171810 e509cac533
commit e2dd4cd05f
298 changed files with 4568 additions and 1991 deletions
--- a/docs/content/en/functions/safe/CSS.md
+++ b/docs/content/en/functions/safe/CSS.md
@@ -0,0 +1,38 @@
+---
+title: safe.CSS
+linkTitle: safeCSS
+description: Declares the provided string as a known "safe" CSS string.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeCSS]
+  returnType: template.CSS
+  signatures: [safe.CSS INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+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:
+
+* <span class="good">`<p style="{{ .Params.style | safeCSS }}">…</p>` &rarr; `<p style="color: red;">…</p>`</span>
+* <span class="bad">`<p style="{{ .Params.style }}">…</p>` &rarr; `<p style="ZgotmplZ">…</p>`</span>
+
+{{% note %}}
+"ZgotmplZ" is a special value that indicates that unsafe content reached a CSS or URL context.
+{{% /note %}}
--- a/docs/content/en/functions/safe/HTML.md
+++ b/docs/content/en/functions/safe/HTML.md
@@ -0,0 +1,44 @@
+---
+title: safe.HTML
+linkTitle: safeHTML
+description: Declares a provided string as a "safe" HTML document to avoid escaping by Go templates.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeHTML]
+  returnType: template.HTML
+  signatures: [safe.HTML INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+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/
--- a/docs/content/en/functions/safe/HTMLAttr.md
+++ b/docs/content/en/functions/safe/HTMLAttr.md
@@ -0,0 +1,60 @@
+---
+title: safe.HTMLAttr
+linkTitle: safeHTMLAttr
+description: Declares the provided string as a safe HTML attribute.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeHTMLAttr]
+  returnType: template.HTMLAttr
+  signatures: [safe.HTMLAttr INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+aliases: [/functions/safehtmlattr]
+---
+
+Given a site configuration that contains this menu entry:
+
+{{< code-toggle file="hugo" >}}
+[[menu.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
--- a/docs/content/en/functions/safe/JS.md
+++ b/docs/content/en/functions/safe/JS.md
@@ -0,0 +1,31 @@
+---
+title: safe.JS
+linkTitle: safeJS
+description: Declares the provided string as a known safe JavaScript string.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeJS]
+  returnType: template.JS
+  signatures: [safe.JS INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+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:
+
+* <span class="good">`<script>var form_{{ .Params.hash | safeJS }};…</script>` &rarr; `<script>var form_619c16f;…</script>`</span>
+* <span class="bad">`<script>var form_{{ .Params.hash }};…</script>` &rarr; `<script>var form_"619c16f";…</script>`</span>
--- a/docs/content/en/functions/safe/JSStr.md
+++ b/docs/content/en/functions/safe/JSStr.md
@@ -0,0 +1,61 @@
+---
+title: safe.JSStr
+linkTitle: safeJSStr
+description: Declares the provided string as a known safe JavaScript string.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeJSStr]
+  returnType: template.JSStr
+  signatures: [safe.JSStr INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+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
--- a/docs/content/en/functions/safe/URL.md
+++ b/docs/content/en/functions/safe/URL.md
@@ -0,0 +1,75 @@
+---
+title: safe.URL
+linkTitle: safeURL
+description: Declares the provided string as a safe URL or URL substring.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [safeURL]
+  returnType: template.URL
+  signatures: [safe.URL INPUT]
+relatedFunctions:
+  - safe.CSS
+  - safe.HTML
+  - safe.HTMLAttr
+  - safe.JS
+  - safe.JSStr
+  - safe.URL
+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" copy=false >}}
+[[menu.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" copy=false >}}
+<!-- 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" copy=false >}}
+<!-- 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