Defining and accessing root objects from configDir

support
1

I want to define menus in a separate config file: /config/_default/menus.toml, but I am struggling to understand how to define a multi-level menu within the menus.toml file and how to access this menu within a template.
Any help would be gratefully received.

2

config/_default/menu.toml

[[main]]
  name = 'Home'
  pageRef = '/'
  weight = 10

[[main]]
  name = 'Products'
  pageRef = '/products'
  weight = 20

[[main]]
  name = 'Services'
  pageRef = '/services'
  weight = 30

Example template here:
https://gohugo.io/templates/menu-templates/

3

Thank you. I appreciate the help and apologies for initially posting to GitHub. I just seemed to have become ‘stuck’ with this… All good now :slight_smile:

4

I have another question to do with this: pageRef seems to be ignored if it reference a sub-directory such as:

[[page]]
    name = '1'
    identifier = 'ch2p1'
    weight = 10
    pageRef = '/learn/chapter-2/p1/'
[[page]]
    name = '2'
    identifier = 'ch2p2'
    weight = 20
    pageRef = '/learn/chapter-2/p2/'

In the above (contained in menus.toml) the pageRef' must be amended to url` for the following code to work:

    {{ range  site.Menus.page }}
    <a href="{{ .URL }}">{{ .Name }}</a>
    {{ end }}

I can’t find any reference to this behaviour in the documentation. Is this just an undocumented feature, or a bug?

Kind regards

5

Why not use .pageRef in your code (instead of .URL)?

6

Nice one. Many thanks.

I searched for ‘pageRef’ in the documentation, but found nothing. BTW, I used .PageRef

Many thanks again.

7

Actually, I rushed in here .PageRef does not output any value. Indeed this is noted in the source documentation :frowning:

8

pageRef did not work with the last trailing slash the last time I tried it because it uses .GetPage with the later following the file/directory path.

9

TLDR

  • A directory is not a section unless it (a) is a top-level directory under content, or (b) contains an _index.md file.
  • Do not include a trailing slash when referring to a regular page.

1) When defining menu entries in site configuration, always set the pageRef property when linking to other pages on the site. Do not set the url property unless you are pointing to an external resource.

2) The pageRef property for a menu entry defined in site configuration is the file path of the target page, relative to the content directory. It is not a URL. To resolve the pageRef property to a page, Hugo uses the same logic as it does with site.GetPage.

For a regular page content/posts/post-1.md, any of these will work:

# Preferred
pageRef = '/posts/post-1' 
pageRef = '/posts/post-1.md' 

# These could be ambiguous
pageRef = 'posts/post-1'
pageRef = 'posts/post-1.md'
pageRef = 'post-1'
pageRef = 'post-1.md'

For a section page content/posts/_index.md, any of these will work:

# Preferred
pageRef = '/posts'
pageRef = '/posts/'
pageRef = '/posts/_index.md'

# These could be ambiguous
pageRef = 'posts/'
pageRef = 'posts/'
pageRef = 'posts'

3) When creating a menu template, never use the .PageRef variable. Site and theme authors were erroneously using this in their menu templates, so I removed it from the relevant documentation. To get the URL of a menu entry, whether it is another page or an external resource, use .URL in your template.

1 Like
10

Again, I owe you a debt of thanks. I have tested all of this and it is as you have described. Could I offer a suggestion that this excellent explanation be added to the Hugo documentation?

11

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