Concern Regarding Empty Table of Contents (TOC) Element Creation


I’ve noticed that even when the Table of Contents (TOC) is empty, Hugo still generates a <nav> element with the id="TableOfContents". I’m concerned about the necessity and potential impact of having this empty TOC element in the generated HTML.


  1. Empty TOC Element: When the TOC is empty, Hugo generates a <nav id="TableOfContents"></nav> in the HTML output.
  2. Unexpected Behavior: This empty TOC element might lead to unexpected behavior, such as displaying an empty TOC section in the UI or causing unnecessary clutter in the HTML.

Desired Outcome:

I would like to ensure that the TOC element is only generated when there is meaningful content to display. I want to avoid creating an empty TOC element when there are no headings present on the page.

Request for Guidance:

  1. Configuration Adjustment: Should I adjust any Hugo configuration settings to prevent the generation of the empty TOC element?
  2. Template Logic: What changes should I make to the template logic to ensure that the TOC is only generated when there are actual headings present on the page?
  3. And I can’t write a if condition based the variable
{{if .TableOfContents }}
  <aside class="toc">
    <p class="toc-heading">In this page</p>
    {{ .TableOfContents }}
{{ end }}

This has nothing to do with Hugo, it’s a matter of the theme you’re using. Hugo does not generate nav elements by itself.

Also, your chances to receive help here are vastly improved if you do not only post a description of the perceived problem, but also a link to the repository.

Yes, it does.

No, it is not.

Yes, it does.

Render the TOC if it contains a list item element:

{{ if in .TableOfContents "li" }}
  {{ .TableOfContents }}
{{ end }}


{{ if strings.Contains .TableOfContents "li" }}
  {{ .TableOfContents }}
{{ end }}

Always? In my projects, it’s the theme that produces the nav element. Hugo doing it is perhaps related to a menu definition in the configuration?

Please test it yourself. This topic is about a table of contents.

1 Like

No @jmooring and @chrillek I use Glodmark to render the HTML

see my attached img

If you don’t want an empty TOC, you should (as always) follow the advice of @jmooring. The alternative would be to add a display: none for a TOC without children in your CSS.

yes @chrillek but if the TableOfContents returns empty we can write check in hugo itself thats a correct way

I agree that this and other aspects of the TOC should have been handled differently, but that train left the station many years ago. If we stop rendering the container when it’s empty, some sites may experience an unexpected layout shift. A contrived example:

<div class="before-content">
  {{ .TableOfContents }}
  <div class="something-else">
#TableOfContents {
  width: 200px;
  float: left;

If we change behavior, the “something-else” div will be pulled to the left, which may or may not be desirable.

There are many ways to render a TOC as described here. Another approach is to use something like tocbot.

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.