Document template content escaping and security rules

[polybuildr]

The original issue is below, but it was not actually a bug, rather a misunderstanding of the way autoescaping (and preventing it) works in Go templates. The issue has been renamed to reflect this.

---

I was trying to use the following code to insert a timestamp into a <time> tag:

<time class="post-date" datetime="{{ .Date.Format "2006-01-02T15:04:05-0700" | safeHTMLAttr }}">{{ .Date.Format "Jan 2, 2006" }}</time>

but this outputs:

<time class="post-date" datetime="2017-05-27T13:49:41&#43;0300">May 27, 2017</time>

note the escaped + as +. Shouldn't safeHTMLAttr allow using a raw +? (Or - for that matter.)

[moorereason]

This is not a bug. It's how Go templates work. It can also be one of the most confusing parts of using Go templates IMO. Namely, how do we properly output content to avoid the Go template engine from escaping it?

There are cases like this one where it doesn't act the way you think it should. We need to provide some great documentation and guidance for these rules.

More examples of confusion:

• https://discuss.gohugo.io/t/safejs-being-ignored/2433
• https://discuss.gohugo.io/t/problems-with-encoding-special-characters-in-json-ld-invalid-escape-sequence/3084
• https://discuss.gohugo.io/t/solved-url-forward-slashes-rendered-quoted-with-backslash/4457

/cc @rdwatters

[polybuildr]

I saw a very large number of these questions, but somehow didn't realise how to fix this. After reading text/template and html/template docs (and doing some thinking :P), I finally realise that type HTMLAttr refers to an entire attribute with value, i.e. foo="bar" and this solves my problem.

<time class="post-date" {{ printf "datetime=%s" (.Date.Format "2006-01-02T15:04:05-0700") | safeHTMLAttr }}>...

works great! It would definitely help if this were documented somewhere more clearly and made easy to find. I only have a preliminary understanding now, but I would love to contribute if it would help. Maybe another section in the Go Template Primer or a new sub division in the Templates section?

I'm editing my initial "bug" report to reflect that this is not a bug.

[digitalcraftsman]

Soon we will switch to a overhauled version of the docs. They actual docs also moved into their own repo. This repo only contains the actual source code. Hence this issue doesn't belong to this repo anymore.

For further discussions, comments etc. please refer to rdwatters/hugo-docs-concept#125.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.