Trying to develop better documentation around these different methods/functions and I’m having a tough time distinguishing between the lot of them…
Also, any thoughts on how to differentiate these functions from jsonify or how to use in combination with safe* or raw (or whatever) would be greatly appreciated.
I think the distinctions need to be documentated after just recently (re)reading the following:
Cheers.
.Plain is the Page content stripped of HTML tags as a string.
.PlainWords is the Page content stripped of HTML as a []string (string slice). Under the hood, we’re using Go’s strings.Fields to split .Plain into a slice.
.RawContent is the raw content read from the content file. Generally, this would be the raw Markdown content prior to any encoding from Hugo.
plainify is a template function that takes a given input, strips it of HTML tags, and returns a string.
jsonify is a template function that takes a given object, encodes it as JSON, and converts it to HTML-safe content.
The safe* family takes a given input and does a type-casting to the thing you want. For example, safeHTML can take a string as input, but returns a template.HTML type. Go HTML templates are context-aware. If you try to print a string with HTML tags in an HTML context, Go will escape all of the HTML tags. In that case, you need to convert the string type to template.HTML so that Go will leave it alone.
Awesome, @moorereason. Thanks. Just the type of succinct description I needed. Now I can build some cool examples out around it. Cheers!
Re. RawContent, its original use case was to use with client-side slide tools, i.e. Javascript rendering of Markdown.
I posted an issue I am having with plainify Plainify problems (more of an opinion than a real defect) · Issue #8732 · gohugoio/hugo · GitHub but there is a note to talk on discord first. I am sorry, never talked on discord yet, but I saw this related issue and another issue about jsonify of plainified text. Basically I see the need of always following plainify with htmlUnescape before using the value anywhere including jsonify. I have yet to be able to use plainify by itself and was curious if plainify should just do htmlUnescape internally because return safeHTML text would also work but would obviously be dangerous. The reason this came up is that when using plainify without htmlUnescape it seems to work until you happen to have any HTML entities in the string which end up being output as plain text instead of their unicode chars. So I end up constantly combing through the code searching for plaininfy without htmlUnescape, markdownify or safeHTML after it.