# 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 following settings are supported: | Setting | Default | Description | |---------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `anchor` | - | Flag indicating to display anchor links on hovering a heading. | | `logo` | - | Address of the brand logo image, e.g. "/img/logo_embedded.svg". The vector image file is expected to be present in your local `static/img` folder. | | `logo-mode` | `false` | {{< release version="v1.15.0" short="true" button-size="sm" inline="true" >}} Flag indicating if the brand logo should support color modes. If set, the navbar searches for images having a matching color-mode suffix such as `-light` or `-dark`. | | `logo-align` | `center` | {{< release version="v1.15.0" short="true" button-size="sm" inline="true" >}} Alignment of the brand logo when the navbar is in collapsed mode, either `start` or `center`. | | `logo-height` | 30 | Height of the brand logo in pixels. | | `color` | - | [Theme color](colors) of the navigation bar. Set the style to set the correct contrast of the menu items. The navigation bar is transparent when no color is set, but is set to the body color when scrolling to enhance the contrast. | | `style` | `light` | Style of the navigation bar, either "light" or "dark". It changes the colors of the menu items accordingly. | | `fixed` | false | Flag indicating to keep the navigation bar fixed at the top of the screen. | | `overlay` | false | {{< release version="v0.23.0" short="true" button-size="sm" inline="true" >}} Flag indicating to render the navigation bar as overlay on top of the page body. In this state, the navigation is transparent and the page body starts at the top of the viewport. The navigation becomes opaque when scrolling and is set to the specified theme `color`. | | `overlayMode` | `dark` | {{< release version="v0.23.0" short="true" button-size="sm" inline="true" >}} Style of the navigation bar when `overlay` is set, either “light” or “dark”. | | `horizontal` | false | {{< release version="v0.21.0" short="true" button-size="sm" inline="true" >}} Flag indicating the second level navigation should render horizontally. By default, the navbar uses regular dropdown menus instead. | | `offset` | `3em` | Applies an [offset to main elements](https://getbootstrap.com/docs/5.3/components/navbar/#placement) when `fixed` is set to true. | | `size` | `md` | Optional breakpoint of the navbar toggler, either "xs", "sm", "md" (default), "lg", or "xl". | | `fontsizeCollapsed` | 6 | Font size of the menu items in collapsed state. The available sizes are `[1..6]`, similar to the size of the headings `[h1..h6]`. | | `search` | true | {{< release version="v0.18.0" short="true" release-state="deprecated" button-size="sm" inline="true" >}} Flag indicating to include a search input. | | `breadcrumb` | false | Flag indicating to add breadcrumb navigation to the top of any single page. List pages are excluded. | | `toc` | true | Flag indicating to enable table of contents globally. Individual pages can override this setting in the frontmatter using the value `includeToc`. | | `sidebar` | true | Flag indicating to enable sidebar navigation globally. If set, a sidebar is displayed when applicable. | | `language.icon` | `fas globe` | {{< release version="v1.12.0" short="true" button-size="sm" inline="true" >}} Icon to use for the language selector. | | `search.enabled` | true | {{< release version="v1.12.0" short="true" button-size="sm" inline="true" >}} Flag indicating to include a search input. | | `search.modal` | true | {{< release version="v1.12.0" short="true" button-size="sm" inline="true" >}} Flag to trigger a modal input form for search queries and results. By default, an input field is added to the navbar instead. | | `search.icon` | "fas magnifying-glass" | {{< release version="v1.12.0" short="true" button-size="sm" inline="true" >}} Icon to use for the modal search button. | The below configuration shows the default configuration set in `config/_default/params.toml`. ```toml [navigation] anchor = true logo = "/img/logo_icon.svg" logo-mode = false logo-align = "center" logo-height = 30 color = "body" fixed = true overlay = false overlayMode = "dark" horizontal = false offset = "5.7rem" breadcrumb = true toc = true sidebar = true size = "md" startLevel = 2 endLevel = 3 maxNumHeadings = 9 [navigation.padding] x = 4 y = 4 [navigation.search] enabled = true modal = true ``` ## Main navigation The main navigation uses [Hugo's menu system](https://gohugo.io/content-management/menus/) 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](https://gohugo.io/content-management/menus/) to generate the menu items. The navigation supports nesting at one level deep. Hinode supports three additional parameters: | Argument | Required | Description | |-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `alias` | No | If set, the active menu item is linked to the specific menu entry instead of being derived from the target URL. | | `button` | No | {{< release version="v0.24.10" short="true" button-size="sm" inline="true" >}} If set, renders the menu item as a (small) button. | | `spacing` | No | {{< release version="v0.24.10" short="true" button-size="sm" inline="true" >}} If set, inserts a spacer. All prior menu items are left aligned, whilst the remaining menu items are right aligned. | The following example defines an example menu configuration called `sample` (the main configuration is called `main`). ```toml [[sample]] name = "Tutorials" pageRef = "/tutorials/" weight = 10 # [[sample]] # name = "Blocks" # pageRef = "/blocks/" # weight = 20 # [[sample]] # name = "Approach" # pageRef = "/blocks/approach/" # parent = "Blocks" # weight = 1 # [[sample]] # name = "Releases" # pageRef = "/blocks/releases/" # parent = "Blocks" # weight = 2 ``` ### 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](documentation) 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](navbar). The following variables are available to modify the styling of the horizontal navigation. You can override them in `assets/scss/theme/_variables.scss`. ```scss $dropdown-transition: opacity .15s ease-in-out !default; $dropdown-horizontal-margin-top: calc((-1.5 * 1rem) - 2px); $dropdown-horizontal-padding-y: calc(1rem + 2px); ``` ## 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](https://getbootstrap.com/docs/5.3/components/offcanvas). In this case, the main navigation receives an additional toggler on the left of the screen. ### Menus > [!IMPORTANT] > The sidebar recognizes multilingual data files. Add the language code as suffix to your data file. For example, `data/blog.en.yml` defines the sidebar menu of the English translation of the blog section. 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. You can optionally provide an internal or external link for the destination page (see the [link shortcode](docs/components/link) for its behavior). By default, Hinode derives the destination from the menu item. The below example defines a group section called `Getting started` with three siblings. A single page `About` is added next. The latter redirects to an external website. ```yml - title: Getting started pages: - title: Introduction - title: Commands - title: Contribute - title: About link: https://example.com ``` 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. ```yml - title: A pages: - title: B pages: - title: C pages: - title: First - title: Second - title: Third ``` You can define separate data files for each available language in a multilingual site. Add the language code as suffix to your data file. For example, `data/blog.en.yml` defines the sidebar menu of the English translation of the blog section. Hinode uses `data/blog.yml` as fallback (or any other [data format supported by Hugo](https://gohugo.io/content-management/data-sources/)). Since Added in v0.27.27 , Hinode renders a link for group items when a matching list page is found. You can suppress this behavior for a group item by setting its link value to `"#"` (the value is double-quoted to ensure the value is not interpreted as a YAML comment). For example, the Hinode docs includes a group item `Components`. The link `/docs/components/` redirects to a list page that shows all available Hinode components. This list page breaks out from the sidebar navigation layout. To avoid navigating to this page, the Hinode docs suppresses this link. Instead, the group item is expanded or collapsed, pending current state. ```yml - title: Components link: "#" pages: - title: Abbr ``` ### Versioning Added in v0.15.0 > [!NOTE] > Release v0.15.0 of Hinode automatically detects the version of the current context. The configuration of the `version` attribute is no longer needed. 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](documentation) 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: ```scss .sidebar { top: var(--navbar-offset); } .sidebar-overflow { top: calc(var(--navbar-offset) + 1rem); max-height: calc(100vh - var(--navbar-offset)); overflow-y: auto; scrollbar-gutter: stable; } .sidebar-item { --bs-border-radius: #{$theme-border-radius}; --bs-border-radius-sm: #{$theme-border-radius}; --bs-border-radius-lg: #{$theme-border-radius}; --bs-border-radius-xl: #{$theme-border-radius}; --bs-border-radius-xxl: #{$theme-border-radius}; color: rgba(0, 0, 0, 0.65); margin-left: 0 !important; display: inline-block; padding: 0.1875rem 0.5rem !important; &.active { color: $primary; } &:hover, &:focus { color: $primary; background-color: tint-color($primary, 90%); } } .sidebar-item-group { --#{$prefix}link-opacity: 0.65; border-radius: #{$theme-border-radius}; &:hover, &:focus { color: $primary; background-color: tint-color($primary, 90%); } > div > a { color: rgba(var(--#{$prefix}body-color-rgb), var(--#{$prefix}link-opacity, 1)); text-decoration: none; cursor: pointer; &:hover, &:focus { color: $primary; } } } .sidebar-item-group > div { padding: 0.1875rem 0.5rem !important; } .btn-toggle-group { padding: 0.25rem 0.5rem; font-weight: 600; color: rgba(0, 0, 0, 0.65); background-color: transparent; &:hover, &:focus { background-color: transparent; } &::before { width: 1.25em; line-height: 0; content: $btn-toggle; transition: transform 0.35s ease; transform-origin: 0.5em 50%; } } .btn-toggle-group[aria-expanded="true"] { &::before { transform: rotate(90deg); } } @if $enable-dark-mode { @include color-mode(dark) { .sidebar-item { --#{$prefix}link-opacity: 0.65; color: rgba(var(--#{$prefix}body-color-rgb), var(--#{$prefix}link-opacity, 1)); &.active { color: $primary-text-emphasis-dark !important; } &:hover, &:focus { color: $primary-text-emphasis-dark !important; background-color: transparent; box-shadow: inset 0 0 0 1px $primary-bg-subtle-dark; } } .sidebar-item-group { color: var(--bs-body-color) !important; &.active { color: $primary-text-emphasis-dark !important; } &:hover, &:focus { color: $primary-text-emphasis-dark !important; background-color: transparent; box-shadow: inset 0 0 0 1px $primary-bg-subtle-dark; } > div > a { &:hover, &:focus { color: $primary-text-emphasis-dark !important; } } } .btn-toggle-group { color: var(--bs-body-color); &:hover, &:focus { background-color: transparent; } &::before { content: $btn-toggle-dark; } } .btn-toggle-group[aria-expanded="true"] { color: var(--bs-secondary-color); } } } ``` ## 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](#basic-configuration). If enabled, all single pages will add breadcrumb navigation to the top of the page. ### Example When enabled, the breadcrumb looks like this: ```markdown {{< breadcrumb path="breadcrumb" >}} ``` ### Customization The breadcrumb is also available as [shortcode](breadcrumb). ## Table of contents Single pages can optionally show an [table of contents](https://gohugo.io/content-management/toc) on the right of the screen. The table of contents is automatically populated 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](#basic-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: ```scss .toc-sidebar { top: calc(var(--navbar-offset) + 1rem); max-height: calc(100vh - var(--navbar-offset)); overflow-y: auto; right: 0; z-index: 2; } ```