Hugo themes with dynamic TOC highlighting

@huyingjie posted a question earlier:

I like table of contents in the sidebar, such as, http://yingjiehu.com/100-Days-Of-Web-Development-Round-1/ . When I scroll down, the table of contents changes. How can I achieve this in Hugo?

to which I replied:

On your current website generated with Hexo with the NexT theme, the Bootstrap Scrollspy plugin is being used. Look for the file js/src/scrollspy.js on your website.

Also, see a demonstration of Bootstrap Scrollspy here:
https://www.w3schools.com/bootstrap/bootstrap_scrollspy.asp

Since this is pure CSS and JavaScript, it is independent of the static-website-generator (Hexo or Hugo) but rather on the theme itself, in this case, the “hexo-next-theme”.

It turns out that some of the Hugo themes have already implemented similar dynamic TOC highlighting, examples include:

  1. Academic, see https://sourcethemes.com/academic/docs/writing-markdown-latex/
  2. Material Docs, see https://themes.gohugo.io/theme/material-docs/adding-content/
  3. DocuAPI, see https://themes.gohugo.io/theme/docuapi/
2 Likes

Though of course, it is understandable that @huyingjie would like something more similar to the existing Hexo “NexT” theme.

It turns out there have been two efforts to port the NexT theme to Hugo:

@leopku’s version is rather outdated now.

@xtfly’s version has the same look-and-feel of the original Hexo NexT theme, though it has started to lag behind too. The main thing though is that dynamic TOC highlighting does not yet work, and is listed as a TODO on https://github.com/xtfly/hugo-theme-next.

NexT seems to be the most popular Hexo theme according to https://en.abnerchou.me/Blog/5c00ca67/, so perhaps it would be an interesting project to port this beautiful theme to Hugo with all the functionalities? :wink:

@huyingjie wrote:

@anthonyfok Thank you. Academic theme does not have table of contents sidebar https://themes.gohugo.io/theme/academic/post/getting-started/

The default Academic theme doesn’t, but its documentation does! And it turns out it is easy to copy the table of content sidebar to your Hugo website when using the Academic theme:

Initial preparation

  1. Run git clone --recurse-submodules https://github.com/sourcethemes/academic-www.git to get the Academic documentation website (this has the TOC sidebar in docs/)
  2. Run git clone --recurse-submodules https://github.com/sourcethemes/academic-kickstart.git to get the Academic kickstart (plain vanilla but fully configured Academic theme).
  3. Run cd academic-kickstart,
  4. Run hugo new post test-post.md
  5. Edit content/post/test-post.md in your favorite editor.
  6. Run hugo server and navigate to the post that you just created. Note that there is no TOC sidebar.

Now, do the magic

Staying inside the academic-kickstart directory:

  1. mkdir layouts
  2. cp -avi ../academic-www/layouts/docs layouts/post (for the single.html template)
  3. cp -avi ../academic-www/layouts/partials/ layouts/
  4. cp -avi ../academic-www/static/css/ static/ which copies static/css/custom.css for the TOC highlighting magic
  5. Edit config.toml, search for custom_css = [] and change it to custom_css = ["custom.css"]

And that should do the trick!

1 Like

For those who are too busy to follow the steps above, check out

which is based on https://github.com/sourcethemes/academic-kickstart
and https://github.com/sourcethemes/academic-www as described above.

Please be sure to add the --recurse-submodules flag when you clone the repository, like so:

git clone --recurse-submodules \
    https://github.com/anthonyfok/academic-kickstart-toc-example.git

so that the base Academic theme is fetched properly.

After running hugo server, you’ll find the example with dynamic TOC at http://localhost:1313/post/toc-test/

This example uses the Hugo Academic theme https://github.com/gcushen/hugo-academic which currently uses Bootstrap v3.3.7 with ScrollSpy. The same dynamic TOC effect probably originated from Bootstrap v3.3.x documentation itself, see https://getbootstrap.com/docs/3.3/javascript/#scrollspy