Docs ToC Scrollspy Module

[giscus[bot]]

Docs ToC Scrollspy Module

Automatically update table of content navigation to indicate which heading is currently active in the viewport.

https://hbstack.dev/modules/docs/toc-scrollspy/

[gavlinski]

Hi, currently the Table of Contents (ToC) displayed in the right-hand sidebar does not support rendering icons using the shortcode format {{< icons/icon lucide shield-check >}}. Instead, it outputs something like <a href="#hahahugoshortcode79s1hbhb-title-text" class="">HAHAHUGOSHORTCODE79s1HBHB Title Text</a>, which appears to be a raw shortcode placeholder.

Would it be possible to either:

• Strip out the icon shortcodes and display only the plain text in the ToC, or
• Properly render the icons within the ToC?

As a workaround, I'm currently using emojis (e.g., 🛡️) copied and pasted directly into the headings, which works but is not ideal.

[razonyang]

Currently, the template uses the TableOfContents for ToC, which is handled by Hugo internally.

String replacing will impact the build performance, which I don't want to do so.

There is a workaround to achieve this by customizing ToC via Fragments, however there is a compatibility issue that the template don't have access to the markup.tableOfContents settings that users rely on.

I created an issue hbstack/docs#1028, but I haven't decided how to do it yet, you can share ideas if any.

[razonyang]

I just request help from Hugo forum, I'll make plans after they reply.

[razonyang]

OK, there is the solution.

1. Create a shortcode for heading icons, e.g. layouts/shortcodes/heading-ico.html.

{{- $vendor := .Get 0 -}}
{{- $name := .Get 1 -}}
{{- partial "icons/icon" (dict "vendor" $vendor "name" $name "size" "1em") | replaceRE "\n" "" | safeHTML -}}

3. And using the new shortcode over than ico within content.

## {{% heading-ico "bootstrap" "house" %}} Heading with icon 

Please note that the {{% ... %}} is required.

Since {{% %}} syntax doesn't handle HTML block contains newlines in newer Hugo version, so you will need to remove it via replaceRE "\n" "" in shortcode.

[gavlinski]

Thanks so much for your support! 🙌
The solution you provided worked perfectly, and I really appreciate how quickly you delivered it.

For reference (in case it's helpful to others), I also found that it's possible to easily hide the svg icons in the ToC (keeping them only on the main page) using CSS. Here's the snippet:

.hb-docs-doc-toc.ps-lg-3.pe-lg-2.text-body-secondary nav#TableOfContents svg {
  display: none !important;
}

Thanks again for the great help!

[razonyang]

You're welcome.