Table of Contents (ToC)

[paddy-exe]

For longer blog posts with a lot of headers it is useful to supply a table of contents so the user can quickly jump to a specific section

Here's two images from the Papermod theme to showcase:

[paddy-exe]

Solved by using the GitHub syntax:

<details>

<summary><b>Table of Contents</b></summary>

0. [Introduction](#introduction)
1. [The structure of Visual Shaders Nodes](#the-structure-of-visual-shaders-nodes)
2. [How to add Visual Shader Nodes in C++](#how-to-add-visual-shader-nodes-in-c)
3. [Compiling Godot from source](#compiling-godot-from-source)
4. [Using the custom Visual Shader Node](#using-the-custom-visual-shader-node)
</details>

and enabling the goldmark "unsafe" renderer option

[markup]
  [markup.goldmark.renderer]
    unsafe = true

Result

@hugo-sid This should probably be documented, right? I also think that this prevents many from seeing the specific Hugo features for code highlighting (at least only the normal Markdown syntax works and not the Hugo one)

[hugo-sid]

Hi Patrick, thanks for the solution. You are correct, this can be solved by using the GitHub syntax.

However, here are few concerns:

• in this way, an user of this theme has to do it on all markdown pages; finding and writing all the headings is cumbersome
• as much as possible we should try to avoid setting unsafe = true for safety reasons

I have a better implementation in mind, which avoids these concerns.

I will post an update regarding this here (soon).

[hugo-sid]

Hi Patrick (@paddy-exe ).

Please take a look at the demo of table of content here and documentation regarding the same here.

Notes:

• I have implemented it using Hugo's {{ .TableOfContents }} function which generates the sub headings automatically.
• Thanks for your tip. I used the <details> and <summary> HTML tags to implement this, in a cleaner way (rather than some JS+CSS code or some libraries). This allows me to keep the theme maintainable and minimal.
• This implementation avoids the concerns that I raised before.

Kindly update your theme, to use this feature.

Feel free to close this discussion if you don't have anything else to say regarding the table of content feature.

Happy blogging :)
Have a good day.

[paddy-exe]

Hey Sid, thank you for the quick implementation! I worked the ToC into my blog and it works beautifully. Closing this discussion now. Thank you very much!

[hugo-sid]

You are welcome Patrick. I'm glad you were able to implement it in your blog.