Maybe you want to add a Table of Contents ( TOC ) to the articles on your Hugo site but don’t know how to do it, or maybe you want to insert a TOC somewhere in the middle of your post. This is the tutorial for you.
1. The TOC configuration
First you need to see if your Hugo theme contains Table of Contents ( TOC ) settings. Open the config.toml
file in your Hugo site folder ( Later we’ll call it YourSite
in this article ), find the parameter tableOfContents
( or toc
), set it to be true
like this:
tableOfContents = true
Then, if your Hugo theme has a TOC configuration, a TOC will be added at the beginning of every post.
Q: What if I don’t want to show the TOC of an article?
A: Go to the front matter of that article, and set:
toc: false
Then only the TOC of that article won’t be shown.
2. How to insert a TOC in the middle of your post?
However, some Hugo themes don’t have Table of Contents ( TOC ) settings, or you may want to insert a TOC somewhere in the middle of the post. In that case, you can use Hugo shortcodes.
Hugo Shortcodes Page introduces shortcodes as this:
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template.
We can think of a shortcode as a function. When we call it, Hugo will render in the way the shortcode defined.
How to use shortcodes?
By written {{% shortcodeName parameters %}}
or {{< shortcodeName parameters >}}
wherever you want to use it in the markdown article. Actually, if you’ve read my first tutorial , you may have already used shortcodes. In it the shortcode figure
is used to display an image and its title.
{{< figure src="/image1.jpg" title="image1_title" >}}
figure
is a built-in shortcode. There is no built-in shortcode for Table of Contents ( TOC ) , so we need to define it, which is a bit hard for beginners. Thankfully the author of Hugo theme hugo-octopress has done it for us. You just need to download this repository on GitHub . Go to YourSite > layouts
folder, create a shortcodes
folder in it if it doesn’t exist. Then copy the toc.html
from the downloaded Hugo-Shortcodes > shortcodes
folder to YourSite > layouts > shortcodes
folder.
To insert TOC somewhere in your article, just write a line: {{% toc %}}
( or {{< toc >}}
).
3. Set the range of headings to be displayed
Sometimes you may find the page doesn’t show all the headings, and you can fix it by setting in YourSite > config.toml
:
[markup]
[markup.tableOfContents]
startLevel = 3
endLevel = 5
The startLevel
and endLevel
refer to the highest and lowest levels of the headings to be shown. For example, the above setting means that the TOC only shows headings between level 3 and level 5.
References
The author of the hugo-octopress theme introduced the use of shortcodes in detail and I find it helpful : https://github.com/parsiya/Hugo-Octopress/blob/master/README.md#shortcodes
Top comments (0)