diff options
Diffstat (limited to 'docs/content/en/functions/safe/HTML.md')
| -rw-r--r-- | docs/content/en/functions/safe/HTML.md | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/docs/content/en/functions/safe/HTML.md b/docs/content/en/functions/safe/HTML.md new file mode 100644 index 000000000..ea3afe8f3 --- /dev/null +++ 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. <a href="https://creativecommons.org/licenses by/4.0/">Some rights reserved</a>.</p> +``` + +[config]: /getting-started/configuration/ |