Why your menu won’t be served
The missing menu
The sectionPagesMenu config setting may not work as you might expect in Hugo menus. I struggled with this for quite a while, but now a long-lasting mystery has been solved, finally. Time to share this, so your struggle may be shorter, or, if you just stumbled upon the problem and immediately found this article here, even nonexistent.
You follow the instructions in the Hugo documentation (https://gohugo.io/content-management/menus/) and see that you can define a menu in the config file (config.toml).
You have the setting in your config, like so:
sectionPagesMenu = 'main'
You have some pages, written in Markdown. You may even have some directories with an index.md file inside.
In your partial template for the header (<theme>/layouts/partials/header.html), you have a code block that should show the menu. It may look similar to this:
{{ range site.Menus.main }}
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
{{ end }}
So you think that stuff should show up in the menu. But there is no menu.
The reason is that this only works for sections.[1] Sections are directories that contain an _index.md file. They are also called branch bundles. Directories which contain an index.md (note the missing underscore at the beginning of the filename) file are called leaf bundles. They are not sections, so they will not appear in the menu, only branch bundles will.
Leaf bundles and branch bundles are the two forms of page bundles. More about the different kinds of bundles can be found here: https://gohugo.io/content-management/page-bundles/.
The Hugo documentation is not overly supportive here. After telling you that you can use the setting, it says:
This creates a menu structure that you can access with site.Menus.main in your templates. See menu templates for details.
A hint that this only works with branch bundles would be nice.[2] After all, it took me some months (which I of course not only spent solving this one problem) to find out what the problem was.
Of course I was not completely blocked by this, as there are other ways to get your menu. One way is to define the menu for a page in the front matter of your page (the stuff right at the beginning of the page), the other is to explicitly define the menu with all its entries in the config (which is what I do, because right now I’m only creating small sites with Hugo).
The menu is served, but the plate is empty
When this problem is solved, a new problem can appear.[3]
It may happen that your branch bundle appears in the menu, but when you click on
the link, you only see an empty page.
The reason is that your list template (which can be found in
<theme>/layouts/_defaults/list.html) is empty, because you created a fresh
theme with hugo new theme <themename>, but you have not yet implemented the
list template.
Branch bundles are considered to be lists by Hugo, so they are processed using the list template. Putting some minimalistic code into your list.html is enough to make the branch bundle render. Something like
{{ define "main" }}
{{ .Content }}
{{ end }}
will do for starters.
Finally, a hint: Making your menus with sectionPagesMenu only works for top-level sections. Subsections like content/livingthings/mushrooms/_index.md will not appear in the menu, whereas content/dinosaurs/_index.md will show up in the menu.