Navigation

Help the user navigate your website using configurable navigation elements.

Hinode supports several types of navigation that utilize Bootstrap elements. The main navigation is positioned on the top of the screen and includes a search input element. An optional secondary navigation is available as sidebar. Next to these navigation items, pages may optionally include a breadcrumb to indicate the current page’s location within the site’s navigational hierarchy. Finally, pages may also include a table of contents element that is linked to the scroll position of the current page.

Basic configuration

The basic configuration of the navigation elements is set in the navigation section of the site parameters. The folllowing settings are supported:

The below configuration shows the default configuration set in config/_default/params.toml.

• /config/_default/params.toml

[navigation]
    anchor = true
    logo = "/img/logo_icon.svg"
    color = "body"
    fixed = true
    offset = "3.8em"
    search = true
    breadcrumb = true
    toc = true
    sidebar = true

Main navigation

The main navigation uses Hugo’s menu system to generate a responsive navigation bar at the top of the page. The navigation bar uses a breakpoint to add a toggler for smaller screens. A language switcher is added automatically if your site supports multiple languages. The language switcher links to the currently translated page if available.

Menus

The navigation bar uses Hugo’s menu system to generate the menu items. The navigation supports nesting at one level deep. Hinode supports an additional parameter called alias. If set, the active menu item is linked to the specific menu entry instead of being derived from the target URL. The following example defines an example menu configuration called sample (the main configuration is called main).

• config/_default/menus/menus.en.toml

[[sample]]
  name = "About"
  pageRef = "/about/"
  weight = 10
  [sample.params]
    alias = true

[[sample]]
  name = "Guides"
  pageRef = "/guides/"
  weight = 30

[[sample]]
  parent = "Guides"
  name = "Getting started"
  pageRef = "/guides/editing/"
  weight = 10

[[sample]]
  parent = "Guides"
  name = "Adding packages"
  pageRef = "/guides/packages/"
  weight = 20

[[sample]]
  parent = "Guides"
  name = "Optimization"
  pageRef = "/guides/optimization/"
  weight = 30

[[sample]]
  name = "GitHub"
  url = "https://github.com/gethinode/hinode"
  weight = 40

Example

The example below illustrates the navigation bar based on the sample configuration defined in the previous paragraph. The About and About (no alias) menu entries illustrate the behavior of the alias parameter. The GitHub menu entry shows an icon to indicate it is an external link and opens in a new window.

Versioning

The main navigation supports versioning too. When configured, a drop-down menu containing the available versions is automatically added. See the documentation configuration for more details.

Customization

Hinode includes a navigation bar at the top of the screen by default. You can modify the configuration in the layouts/_default/baseof.html file. The navigation bar is also available as shortcode.

Sidebar navigation

Hinode supports optional sidebar navigation. It is intended to be used as companion to the main navigation and is typically used in content-heavy sections, such as documentation pages. On smaller screens, the sidebar is replaced with an offcanvas element. In this case, the main navigation receives an additional toggler on the left of the screen.

Menus

Inspired by Bootstrap’s documentation site, Hinode uses a separate configuration file for the sidebar menus. A sidebar can be configured for each main section of the site. For example, the sidebar menu of the docs section is defined in data/docs.yml. The sidebar menu supports group items and single page items. The below example defines a group section called Getting started with three siblings. A single page About is added next.

- title: Getting started
  pages:
    - title: Introduction
    - title: Commands
    - title: Contribute
- title: About

Menu items can be nested within each other. The below example defines three content pages at the relative path A/B/C. The navigation path should be similar to the slug of the individual pages.

- title: A
  pages:
    - title: B
      pages:
        - title: C
          pages:
            - title: First
            - title: Second
            - title: Third

Versioning

You can create versioned files for your menu data by adding a version suffix to the data file. For example, data/docs-1.0.yml contains the menu data for the docs menu of version 1.0. Hinode uses data/docs.yml as default sidebar navigation data when no versioned file is available. See the documentation configuration for additional options.

Customization

The file assets/scss/components/_sidebar.scss contains the styling of the sidebar. It refers to a button $btn-toggle that is defined in assets/scss/common/_icons.scss. It also defines the spacing to be added to the page’s main content section when using a fixed navigation bar:

• /assets/scss/components/_sidebar.scss

.sidebar {
    top: $navbar-offset;
}

.sidebar-overflow {
    top: $navbar-offset;
    max-height: 90vh;
    overflow-y: auto;
}

.sidebar-item {
    color: rgba(0, 0, 0, 0.65);
    margin-left: 0 !important;
    padding-left: 0.85rem !important;
    display: inline-block;

    &.active,
    &:hover,
    &:focus {
        color: black;
    }
}

.btn-toggle {
    padding: 0.25rem 0.5rem;
    font-weight: 600;
    color: rgba(0, 0, 0, 0.65);
    background-color: transparent;

    &:hover,
    &:focus {
        color: black;
        background-color: tint-color($primary, 90%);
    }

    &::before {
        width: 1.25em;
        line-height: 0;
        content: $btn-toggle;
        transition: transform 0.35s ease;
        transform-origin: 0.5em 50%;
    }
}

.btn-toggle[aria-expanded="true"] {
    color: black;

    &::before {
        transform: rotate(90deg);
    }
}

.btn-toggle-nav a {
    padding: 0.1875rem 0.5rem;
    margin-top: 0.125rem;
    margin-left: 1.25rem;

    &:hover,
    &:focus {
        background-color: tint-color($primary, 90%);
    }

    &.active {
        font-weight: bold;
    }
}

@if $enable-dark-mode {
    @include color-mode(dark) {
        .sidebar-item {
            color: var(--bs-tertiary-color);
            margin-left: 0 !important;
            padding-left: 0.85rem !important;
        
            &.active,
            &:hover,
            &:focus {
                color: var(--bs-secondary-color);
            }
        }

        .btn-toggle {
            color: var(--bs-tertiary-color);
        
            &:hover,
            &:focus {
                color: $secondary;
                background-color: tint-color($primary, 90%);
            }
        
            &::before {
                content: $btn-toggle-dark;
            }
        }

        .btn-toggle[aria-expanded="true"] {
            color: var(--bs-secondary-color);
        }

        .btn-toggle-nav a {
            padding: 0.1875rem 0.5rem;
            margin-top: 0.125rem;
            margin-left: 1.25rem;

            &:hover,
            &:focus {
                color: $secondary;
                background-color: tint-color($primary, 90%);
            }

            &.active {
                font-weight: bold;
            }
        }
    }
}

Breadcrumb

Hinode supports optional breadcrumb navigation. The breadcrumb indicates the current page’s location within the site’s navigational hierarchy. It is automatically populated by Hugo. Enable the breadcrumb in the basic navigation configuration. If enabled, all single pages will add breadcrumb navigation to the top of the page.

Example

When enabled, the breadcrumb looks like this:

Customization

The breadcrumb is also available as shortcode.

Table of contents

Single pages can optionally show an table of contents on the right of the screen. The table of contents is automatically popuplated based on the headings within the page content (two levels deep). The table of contents is hidden if it has less than two items. On smaller screens, a drop-down menu is added to the top of the page. Enable the table of contents in the basic navigation configuration. If enabled, all single pages will show the element, unless disabled in the page’s frontmatter.

Customization

The file assets/scss/components/_toc.scss defines the styling of the table of contents element. It adds spacing to align the element to the sidebar, amongst other styling:

• /assets/scss/components/_toc.scss

.toc-sidebar {
    grid-area: toc;
    right: 0;
    z-index: 2;
    height: calc(100vh - 5rem);
    overflow-y: auto;
    top: 5rem;
}