Build the right-side table of contents from javascript

assets/scss/main.scss

@@ -29,6 +29,7 @@
 @import "taxonomy";
 @import "drawio";
 @import "shortcodes";
+@import "tocbot";
 
 @if $td-enable-google-fonts {
     @import url($web-font-path);

layouts/partials/scripts.html

@@ -80,4 +80,22 @@
 {{ end -}}
 
 <script src='{{ "js/tabpane-persist.js" | relURL }}'></script>
+
+{{ if .Site.Params.jstoc.enable }}
+<!-- Initialize tocbot -->
+<script src="/js/tocbot.min.js"></script>
+<script type="text/javascript">
+    tocbot.init({
+        // Where to render the table of contents.
+        tocSelector: '.td-toc',
+        // Where to grab the headings to build the table of contents.
+        contentSelector: '.td-content',
+        // Which headings to grab inside of the contentSelector element.
+        headingSelector: '{{ with .Site.Params.jstoc.custom_headings }}{{ . }}{{ else }}h2, h3, h4{{ end }}',
+        // ignore headings that are hidden in DOM
+        ignoreHiddenElements: true
+    });
+</script>
+{{ end }}
+
 {{ partial "hooks/body-end.html" . -}}

userguide/content/en/docs/adding-content/lookandfeel.md

@@ -287,3 +287,28 @@ Both `head.html` and `scripts.html` are then used to build Docsy's [base page la
 </html>
 ```
 
+## Sidebar table of contents
+
+By default, Docsy shows the table of contents for the current page in the right sidebar using the built-in function of Hugo. You can replace that with a JavaScript-based ToC that uses the [https://tscanlin.github.io/tocbot/](Tocbot library) by setting the following in your `config.toml` file:
+
+```toml
+[params.jstoc]
+enable = true
+```
+
+By default, h2-h4 headings are included in the sidebar, which includes tips and warnings if you are using the [alert shortcode of Docsy](/docs/adding-content/shortcodes/#alert). To change that,
+provide a comma-separated list of the headings to include in the `custom_headings` parameter, for example:
+
+```toml
+[params.jstoc]
+enable = true
+custom_headings = "h2, h3"
+```
+
+Compared to the default sidebar ToC, this solution:
+
+- has a marker that shows the current location of the screen (useful for long pages)
+- shows the correct title even if the title contains a shortcode
+- shows the title in the toc even if it was included from another file
+
+![Screenshot of JavaScript-based sidebar table of contents](/images/sidebar-toc-with-tocbot.png)