Front matter title not showing in TOC

[robertmarkbram]

I am using the Hugo Learn Theme: Learn Theme for Hugo :: Documentation for Hugo Learn Theme

When I set title on a document, it uses that as the first H1 in the page, which is fine. I can adopt the pattern of only using second level headings and beyond in my markdown.

But the table of contents generated for me doesn’t include the first H1, which makes the TOC look off.

If I have a page like this:

---
title: Objects and Stuff
---

## Big Objects

Big Objects

# Little Objects

Little Objects

This is what the TOC looks like.

It looks like the generated TOC isn’t taking into account the front matter title, but if I go ahead and ad my own first level title, it screws up the look of the page because I get two H1s in the HTML.

Am I missing something?

Rob

[idarek]

I think you using your headings wrong

You got title which is H1 than you got big objects that is H2 and little which is again H1 you shall only have one H1 on your page.

TOC is picking H2-H6 as title is reserved to H1

Ref:

Google Explains How to Use Headings for SEO

[robertmarkbram]

Thanks Idarek - I fixed up my markdown below to better show the issue I am describing.

TOC is picking H2-H6 as title is reserved to H1

The TOC does pick up H1s though!

1. Example 1 - I define my own level 1 header in markdown

   The markdown:

   ---
   title: Objects and Stuff
   ---
   
   # I like Objects
   
   Page about objects.
   
   ## Big Objects
   
   Big Objects
   
   ## Little Objects
   
   Little Objects
   

   The resulting page, where I am hovering the mouse over the top left “TOC dropdown” icon to show the TOC::

   
   1. The Hugo Learn Theme generated TOC is great.
   2. The HTML body is not so great . My page looks odd because I have two H1s in the HTML, one from title and one from my own level 1 heading.

2. Example 2 - only use level 2 headings and below.

   The markdown:

   ---
   title: Objects and Stuff
   ---
   
   ## Big Objects
   
   Big Objects
   
   ## Little Objects
   
   Little Objects
   

   The resulting page, where I am hovering the mouse over the top left “TOC dropdown” icon to show the TOC:

   
   1. The Hugo Learn Theme generated TOC is still trying to display a level 1 heading and failing, looking odd.
   2. But The HTML body looks good, using the default H1 generated from title.

I hope that better describes what I am trying to fix. I don’t mind either approach: writing my own level 1 headings or letting Hugo pick title and make a H1 out of it. I don’t mind if I need to put to some custom work to fix either situation. But I am also interested in what the “Hugo best practice” is, if I can do that.

Rob

[idarek]

You need to look specifically how theme is working as it may different approach to TOC but still, remember to avoid H1 in content.

[McShelby]

Is this with the latest version of the Learn theme? In the past they fixed issues regarding toc indention.

Or try out my fork

Basically it doesn’t make sense to print out the h1 in the toc as it should the only h1 in the whole document and so would only add up to the nesting without any gain.

[robertmarkbram]

I found the solution. You can use markup configuration to tell the whole Hugo site start and end level for the TOC.

I add this to my config.toml:

  [markup.tableOfContents]
    endLevel = 5
    ordered = false
    startLevel = 2

And now the TOC will not render an entry for the H1/level 1 header.

Next I am going to figure out which option I like more:

1. Let the HTML H1 be generated from title and not use any level 1 headings in my markdown.
2. Remove HTML H1 generation form title globally and always set my own level 1 heading.

I think I like the second option better, because then my markdown documents will make more sense outside of Hugo.

Rob

[idarek]

Consider always Title of a page as H1 for SEO aspect.