How To Generate Table of Content For Your Blogs in Hugo

A well-structured table of contents (TOC) can significantly enhance the user experience on your Hugo-powered website. It provides readers with a quick overview of your content's structure and allows them to navigate effortlessly through your articles. Hugo, a fast and flexible static site generator, makes it easy to generate dynamic TOCs for your content. In this guide, we'll explore how to use Hugo's built-in capabilities to create and customize the table of contents for your web pages.

Add Table of Contents in Hugo

To create a table of contents (TOC) on a Hugo website, you can use the built-in support for generating TOCs. Hugo uses Markdown for content, so you can leverage Markdown's automatic TOC generation.

Here's how you can create a table of contents in Hugo:

1. Add Headings: In your Markdown content file (e.g., content/post/my-post.md), use Markdown headings (e.g., ##, ###) to structure your content. Hugo will automatically generate the TOC based on these headings.

## Section 1

Some content here.



### Subsection 1.1

More content.



## Section 2

Another section.

2. Render the TOC: To render the TOC in your content, use the {{ .TableOfContents }} shortcode where you want the TOC to appear in your content. Go to layouts\posts\single.html and paste the following code:

          {{ .TableOfContents }}

3. Customize Styling: You can use CSS to style the generated TOC according to your website's design. Customize the CSS in your Hugo theme or in your custom CSS file.

After making these changes, your Hugo website should have an automatically generated table of contents for each page with appropriate headings. Now test the changes by using the command line “huge serve”.

How to Insert a TOC In the Middle of Your Post?

To insert a table of contents (TOC) in the middle of your post in Hugo, you can use Hugo's shortcodes and Markdown. Here's a step-by-step guide on how to do this:

1. Create Your TOC Shortcode:

Start by creating a custom shortcode that generates the table of contents. In your Hugo project, navigate to the "layouts/shortcodes" directory, and create a new HTML template file for your TOC shortcode. You can name it something like "custom-toc.html."

Inside "custom-toc.html" add the following code:

        

 <div class="custom-toc">

   {{ .Page.TableOfContents }}

 </div>

     

2. Use the TOC Shortcode in Your Content:

In your Markdown content file (e.g., "content/post/my-post.md"), place the TOC shortcode where you want the TOC to appear in the middle of your post. You can do this by using Hugo's shortcode syntax:

## Section 1

Some content here.



### Subsection 1.1

More content.



{{< custom-toc >}}



## Section 2

Another section.

That’s it. Now test the changes by using the command line huge serve.

Customize TOC List Style and Heading Levels

To customize the table of contents (TOC) list style and level in Hugo, you can adjust the TOC configuration in your Hugo project's config.toml file. Specifically, you can control the list style (ordered or unordered) and the start and end heading levels to include in the TOC. 

Here's how to do it:

1. Open Your config.toml File: Locate and open the config.toml file in the root directory of your Hugo project using a text editor.

2. Configure the TOC Settings: Inside the config.toml file, you can find the [markup] section where you can configure the TOC settings. If this section does not exist, you can create it. Add or modify the TOC settings as needed:

[markup]

  [markup.tableOfContents]

    startLevel = 2

    ordered = true

    endLevel = 4

StartLevel: Set this to the lowest heading level you want to include in the TOC. For example, if you want to include up to <h2> headings, set startLevel to 2.

endLevel: Set this to the maximum heading level you want to include in the TOC. For example, if you want to include up to <h4> headings, set endLevel to 3.

Ordered: Set this to true for an ordered (numbered) list or false for an unordered (bulleted) list.

Now save the config.toml and test the changes by using the command line “huge serve”.

With the added feature of the dynamic table of contents, you can take your Hugo site to the next level. In this guide, we've covered the essential steps to enable and customize the table of contents generation in Hugo. By structuring your content with headings, you can offer your audience an intuitive way to explore your articles, tutorials, and documentation.

Feeling uncertain about where to start? Look no further, as StaticMania is at your service! Our dedicated website development team of experts will help you to guide you through every stage of your journey. Don't hesitate, contact us now to kickstart your adventure.