Menus

The menu on the left side of the page is implemented with Hugo menus. To add a page to a menu, you add front matter to the content to tell Hugo which menu to add the page to and where in that menu to add it.

Hugo menus abstract the structure of the menu away from the content’s directory structure on disk. This means we can rearrange the menu without moving files, which breaks URLs and requires painful lists of aliases.

They also natively support including external links by specifying the content in the site’s configuration.

This Site’s Menus

The site defaults to using the products menu. The leftmenu front matter lets you define which left menu a piece of content uses,.

• The Products section uses the products menu at the top level.

• Each product has its own dedicated menu, like droplets for the Droplets section, which is used in our IA layouts.

• The Reference section uses the reference menu (set using leftmenu).

• The Support section is a taxonomy, and uses the support taxonomy-based menu.

• The Glossary section is a taxonomy, and uses the glossary taxonomy-based menu.

• Release Notes are a taxonomy, and use the release-notes taxonomy-based menu.

Menu Front Matter

Here’s a quick reference of the front matter fields that might be in the menu:

menu:
    products:
        parent: # parent page identifier, or omit for top level menu entry
        identifier: # custom identifier for this page, if necessary
        weight: # context-specific weighting, if necessary
        pre: # navicon name
        post: # availability pill, primarily meant for the products section

The sections below walk through this front matter in detail.

Basics of Nesting Menus

The front matter fields under menu: tell Hugo which menu to add the page to and where in the menu to add it. The most basic example is the line menu: products, which would add that content to a menu called products.

Our products menu is nested, not flat. This means we also need to specify which page the current page should be nested under.

menu:
    products: # Add to the products menu
        parent: some-page-identifier # Nest under the page with this identifier

A page’s identifier is determined by it’s front matter as described in the nesting documentation: first by name, then linktitle, then title, overridden if identifier is set explicitly.

Warning

If two pages have the same identifier, Hugo throws an error, similar to errors for ambiguous relrefs. In our content, this is most likely to happen when multiple pieces of content have no name set and share the same linktitle (like “Quickstart”).

To fix this, specify a unique identifier for the pages in conflict:

menu:
    products:
        identifier: a-short-readable-and-unique-string

You can then use this identifier to reference that page in any parent fields.

Nav Icons, Availability Pills, External Links

The pre and post fields are meant for content that goes before and after the page link in the menu, respectively. We use pre for nav icons (use the name of the nav icon) and post for availability pills (use “early” or “beta”) or external links (use “external”).

menu:
    products:
        pre: spaces # navicon name
        post: beta # availability

Note

Setting the menu’s post field only impacts the menu. To add availability pills to the H1 of a page, use the availability front matter.

Weighting

Hugo orders the content in a section based on that content’s front matter. Weight is the first field Hugo looks for to determine ordering. The lower the weight, the higher the position in the menu, scoped to that section.

By vague convention, we weight the pages in a section in multiples of 5: 5, 10, 15, etc. The items always visible in the products menu are weighted as one “section”.

You can weight content within context of a menu:

menu:
    products:
        weight: 10

If you don’t, Hugo falls back the weight defined in the rest of the page’s front matter, if it exists. This is helpful when cascading: each child page can define its weight at the top level of its front matter without having to re-add a cascading menu definition from the section root.

# Section root front matter
title: This Sure Is A Page
linktitle: A Page
menu:
    products:
        identifier: surely-a-page
cascade:
    menu:
        products:
            parent: surely-a-page

# Child page front matter
title: This Is A Child Page
linktitle: Child Page
weight: 10

You can see examples of this in action in the how-to sections of our product IA.