Allow HTML in TOC sidebar of documents

[myrthos]

I had the need to add a HTML tag to the TOC for documentation. In this case <small>. it would look something like this in the yaml file:

- title: Peripheral
  pages:
    - title: CLC <small>Configurable Logic Cell</small>
    - title: CLK <small>Clock Circuitry</small>
    - title: CLR <small>Clock Reference</small>

This messes things up as the tags are not used and the link is a mess. I fixed both issues in sidebar.html by changing $doc_slug to {{- $doc_slug := $title | plainify | urlize -}}
And changing {{ $title }} to {{ $title | safeHTML }}`

Ideally I would have wanted to limit the allowed set of html tags (like small, em, sup and sub), but have no idea how to do that in Hugo, without making it complicated.

My suggestion is to add to Hinode, the support for HTML tags in the side bar.
I have a solution, so it is not necessary for me, but I just think it might be useful to others as well to have that functionality.

[markdumay]

It’s an interesting suggestion. A markdown-only approach would be preferred. The safeHTML declaration is all or nothing, so it wouldn’t improve anything (from a security perspective) to whitelist any HTML tags during post processing. I don’t believe there is any Markdown equivalent to produce small text though.It reminds me to look into the safeHTML configuration of the Hinode template. It should be disabled by default without breaking anything. The site admin can then deliberately adjust this setting.Your suggestion would be helpful to others, as long as they can still decide not to enable safeHTML globally. Should we use the Goldmark configuration for this?On 22 Aug 2023, at 18:53, myrthos ***@***.***> wrote: I had the need to add a HTML tag to the TOC for documentation. In this case <small>. it would look something like this in the yaml file: - title: Peripheral pages: - title: CLC <small>Configurable Logic Cell</small> - title: CLK <small>Clock Circuitry</small> - title: CLR <small>Clock Reference</small> This messes things up as the tags are not used and the link is a mess. I fixed both issues in sidebar.html by changing $doc_slug to {{- $doc_slug := $title | plainify | urlize -}} And changing {{ $title }} to {{ $title | safeHTML }}` Ideally I would have wanted to limit the allowed set of html tags (like small, em, sup and sub), but have no idea how to do that in Hugo, without making it complicated. My suggestion is to add to Hinode, the support for HTML tags in the side bar. I have a solution, so it is not necessary for me, but I just think it might be useful to others as well to have that functionality. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[myrthos]

Markdown doesn't support sup and sub either, which are two other tags, I could see myself using. I understand to not allow html in markdown, which has a setting in Goldmark already. It is certainly safer.

An alternative solution I thought of, instead of html or markdown, is using css styling by means of a shortcode. So, something like this: - title: CLC {{< style "small" >}}Configurable Logic Cell{{< /style >}}

That would allow someone to go really wild on creating styles (although many already exist) and it can also be used in markdown, thus reducing the need further for using html in markdown.

It would need a regular expression I think to remove the shortcode tags in order to be able to create the link.

[myrthos]

I took the effort and created a shortcode that does what I mentioned above. I named it mstyle. I prefix my shortcodes and partials with the letter 'm', hence the name mstyle. It is a very simple shortcode (I took your link shortcode to see how named/unnamed params are used).

{{- $class := "" -}}
{{ $text := trim .Inner " \r\n" | .Page.RenderString | safeHTML }}

{{ if .IsNamedParams }}
    {{- $class := .Get "class" -}}
{{ else }}
    {{- $class = .Get 0 -}}
{{ end }}

{{ if not $class }}
    {{- errorf "shortcode mstyle: Expected param 'class': %s" .Position -}}
{{ else }}
    <span class="{{ $class }}">{{ $text }}</span>
{{ end }}

Furthermore in sidebar.html the following is to be changed:
$doc_slug is changed to {{- $doc_slug := $title | replaceRE "{{<.+?>}}" "" | urlize -}}
The two occurrences of {{ $title }} are changed to {{ $title | $page.RenderString }}

As an example, the data file:

- title: Peripheral
  pages:
    - title: CLC {{< mstyle "small" >}}Configurable Logic Cell{{< /mstyle >}}
    - title: CLK {{< mstyle "sup" >}}Clock Circuitry{{< /mstyle >}}
    - title: CLR {{< mstyle "sub" >}}Clock Reference{{< /mstyle >}}

small is an existing class so it doesn't need an extra class definition, but sup and sub do.

.sup {
    vertical-align: super;
    font-size: smaller;
    line-height: normal;
}

.sub {
    vertical-align: sub;
    font-size: smaller;
    line-height: normal;
  }

it looks like this.

Obviously this is not what my menu is going to look like, I just use it as an example.

The good thing is that it no longer needs HTML.

[myrthos]

I found out that the shortcode I listed needs and extra - in the else and end surrounding the span to remove the generated spaces before and after the span. Otherwise, water would become H ₂ O instead of H₂O.

[markdumay]

I'm adding a few new shortcodes to release v0.19, including sub and sup. We could then apply Page.RenderString to menu items, without having to resort to regex replacements. What do you think?

[myrthos]

I'm not sure that I understand how that would work. The regex is for creating the link from the title (from the yaml file), without it the link would still contain the HTML as text, as the shortcode is part of the title.

As I don't understand, I just tested it in my mpl branch, where I have this working currently.

The yaml line for one of the titles looks like this: - title: CLC {{< mstyle "small" >}}Configurable Logic Cell{{< /mstyle >}}
Processing that with .Page.RenderString will execute the shortcode and replace it with a span and the small class, so the menu entry becomes: CLC <span class="small">Configurable Logic Cell</span>, which looks exactly as I want it.

For creating the link in sidebar.html, I removed the regex and replaced it with $page.Renderstring. The result is that it will just execute the shortcode and I get a link that looks like this: http://localhost:1313/docs/mpl/peripheral/clc-span-classsmallconfigurable-logic-cell/span/. So, the HTML code has become part of the link. Using the RenderString on the already processed shortcode, will create the link http://localhost:1313/docs/mpl/peripheral/clc--raw-html-omitted--configurable-logic-cell--raw-html-omitted--/.
And with the regex, I end up with the correct link: http://localhost:1313/docs/mpl/peripheral/clc-configurable-logic-cell/.

So, I am using RenderString to make sure the shortcode is executed properly for displaying the title. But I don't understand how you would create the correct link to the document, with only a RenderString.