mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Prepare for new sub tree

Browse Source 
See #11925
This commit is contained in:
Bjørn Erik Pedersen
2024-01-27 10:47:28 +01:00
parent 1083bf7c08
commit fc7de7136a
1157 changed files with 0 additions and 64232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/content/en/functions/safe/CSS.md
View File

@@ -1,33 +0,0 @@
---
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 %}}

39
docs/content/en/functions/safe/HTML.md
View File

@@ -1,39 +0,0 @@
---
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/

55
docs/content/en/functions/safe/HTMLAttr.md
View File

@@ -1,55 +0,0 @@
---
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

26
docs/content/en/functions/safe/JS.md
View File

@@ -1,26 +0,0 @@
---
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>`

55
docs/content/en/functions/safe/JSStr.md
View File

@@ -1,55 +0,0 @@
---
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

70
docs/content/en/functions/safe/URL.md
View File

@@ -1,70 +0,0 @@
---
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

14
docs/content/en/functions/safe/_index.md
View File

@@ -1,14 +0,0 @@
---
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