Menu Configuration

The documentation site, built with Hugo, utilizes a flexible menu configuration system to generate its navigation structures. This system relies on YAML configuration files located in config/_default/menus/ to define the menu hierarchy. There are two primary menus: the main navigation menu (main.en.yaml) for general documentation, and a specialized API menu (api.en.yaml) for the API reference section.

While the main menu is manually curated, the API menu is dynamically generated by Node.js scripts that parse OpenAPI specification files. This hybrid approach allows for both structured, hand-crafted navigation for documentation and automated, up-to-date navigation for the extensive API reference. The Hugo templating engine, specifically layouts/partials/nav/left-nav.html and layouts/api/list.html, consumes these configurations to render the final HTML navigation elements.

Menu Architecture Overview

The site's navigation is primarily driven by two separate menu configurations, which are processed by Hugo's templating engine to generate the user-facing navigation panels.

This diagram illustrates the flow from YAML configuration files through the Hugo build process to the final rendered HTML navigation components.
Sources: layouts/partials/nav/left-nav.html, layouts/api/list.html, config/_default/menus/main.en.yaml, config/_default/menus/api.en.yaml

Main Navigation

The main navigation, rendered on the left side of most documentation pages, is defined in config/_default/menus/main.en.yaml. This file contains a hierarchical structure of menu items.

Sources: config/_default/menus/main.en.yaml, layouts/partials/nav/left-nav.html

Structure and Properties

Each entry in main.en.yaml represents a link in the navigation and can have several properties. The menu supports a nested structure with up to four levels of depth.

Sources: config/_default/menus/main.en.yaml, layouts/partials/nav/left-nav.html:18-29

Rendering Logic

The layouts/partials/nav/left-nav.html template is responsible for rendering the main navigation. It recursively iterates through the main menu object provided by Hugo.

1. It starts by iterating through the top-level menu items.
2. For each item, it creates a <li> element with a link <a>.
3. If an item has children (.HasChildren), it creates a nested <ul> and recursively renders the child items.
4. The template supports up to four levels of nesting.
5. The data-path attribute on each link is constructed from the item's URL, which is used by client-side scripts.

{{/* layouts/partials/nav/left-nav.html - Simplified rendering logic */}}
{{ range .Site.Menus.main }}
    {{ if .HasChildren }}
        <p class="h5 text-uppercase fw-bold">{{.Name}}</p>
        <ul class="list-unstyled">
            {{ range .Children }} {{/* LEVEL 1 */}}
                <li class="nav-top-level ...">
                    <a href="{{ .URL | relLangURL }}" ...>
                        <span>{{ .Name }}</span>
                    </a>
                    <ul class="list-unstyled sub-menu ...">
                        {{ range .Children }} {{/* LEVEL 2 */}}
                            ...
                                {{ if .HasChildren }}
                                    <ul class="list-unstyled sub-menu ...">
                                    {{ range .Children }} {{/* LEVEL 3 */}}
                                        ...
                                            {{ if .HasChildren }}
                                                <ul class="list-unstyled sub-menu ...">
                                                {{ range .Children }} {{/* LEVEL 4 */}}
                                                    ...
                                                {{ end }}
                                                </ul>
                                            {{ end }}
                                    {{ end }}
                                    </ul>
                                {{ end }}
                        {{ end }}
                    </ul>
                </li>
            {{ end }}
        </ul>
    {{ end }}
{{ end }}

Sources: layouts/partials/nav/left-nav.html:18-103

API Navigation

The API reference section uses a separate menu defined in config/_default/menus/api.en.yaml. This menu is partially handwritten and partially auto-generated from OpenAPI specifications.

Sources: config/_default/menus/api.en.yaml, assets/scripts/build-api-pages.js, assets/scripts/build-reference-pages.js

Structure and Properties

The api.en.yaml file follows a similar structure to the main menu but includes additional custom parameters used by the API page templates.

Sources: config/_default/menus/api.en.yaml, assets/scripts/build-api-pages.js:63-75, assets/scripts/build-reference-pages.js:63-75

Automated Menu Generation

The assets/scripts/build-api-pages.js and assets/scripts/build-reference-pages.js scripts contain an updateMenu function that populates the api.en.yaml file. This process ensures the API navigation stays in sync with the OpenAPI specifications.

The generation process is as follows:

1. The script reads the existing api.en.yaml file.
2. It removes all entries marked with generated: true to start fresh while preserving any manually added items.
3. It processes an array of OpenAPI specification files (e.g., for v1 and v2).
4. For each spec, it iterates through tags, which become top-level parent menu items.
5. It then iterates through all paths and their associated HTTP methods (actions).
6. For each action, it creates a child menu item under the corresponding tag. It populates the name from the action's summary and sets the parent to the tag's identifier.
7. Crucially, it populates the params object with metadata like API versions, operationids, and unstable status, which is essential for the rendering logic on the API pages.
8. The newly constructed menu array is written back to config/_default/menus/api.en.yaml.

This flowchart shows the process of generating the API menu from OpenAPI specifications.
Sources: assets/scripts/build-api-pages.js:19-100, assets/scripts/build-reference-pages.js:19-100

API Menu Consumption

The layouts/api/list.html template uses the generated api menu to construct the content of each API section page.

The rendering flow is as follows:

1. The template identifies the current API section based on the page's title (e.g., "Monitors").
2. It finds the corresponding top-level entry in the api menu.
3. It then iterates through the children of that menu item, which represent the individual API endpoints.
4. For each endpoint, it uses the params (especially operationids and versions) stored in the menu item to fetch the detailed endpoint data from the full, dereferenced OpenAPI specification loaded into Hugo's data context.
5. This data is then used to render the endpoint's documentation, including its URL, description, parameters, request body, responses, and code examples.

This sequence diagram shows how the API list template uses the api menu to dynamically build the page content from OpenAPI spec data.
Sources: layouts/api/list.html:48-70