Skip to content
Last updated

The navbar appears across the top of the website. You can configure the links and groups of links that appear on the navbar of your site, or hide the navbar altogether. The navbar is a good location for top-level category or frequently-used links.

Options

OptionTypeDescription
itemsItem | GroupList of items in the Navbar.

hide

boolean

Specifies if the navbar should be hidden. Default: false.

The navbar.hide option also supports page-level configuration using front matter.

Group object

OptionTypeDescription
groupstringREQUIRED. Name of the group.
groupTranslationKeystringSpecifies the group name key used for localization.
itemsItemREQUIRED. List of items. The navbar for the default theme may only have one level of depth to groups.
linkedSidebars[string]Array of relative paths to sidebar files. This option will add the navbar item to a sidebar's breadcrumbs. Only effective for top-level navbar items.
iconstringA Font Awesome or relative path to icon image file. Font Awesome icons can be prefixed with type: duotone, solid, regular or brands. Example: book, duotone book, ./images/config-icon.svg.
externalbooleanOpen link in new browser tab. Default is false.
pagestringMUTUALLY EXCLUSIVE. Path to the file which represents the page to link to. Mutually exclusive with the href option. If you use the page option, and do not include the label option, the text for the link on the sidebar will match the level 1 heading of the page.
hrefstringMUTUALLY EXCLUSIVE. URL to link to. Mutually exclusive with the page option. If you use the href option, and do not include the label option, the text for the link on the sidebar will match the href option's value.

Item object

OptionTypeDescription
pagestringCONDITIONALLY REQUIRED. Path to the file which represents the page to link to. Mutually exclusive with the href option. If you use the page option, and do not include the label option, the text for the link on the sidebar will match the level 1 heading of the page.
hrefstringCONDITIONALLY REQUIRED. URL to link to. Mutually exclusive with the page option. If you use the href option, and do not include the label option, the text for the link on the sidebar will match the href option's value.
labelstringLink text displayed for the item.
labelTranslationKeystringLink text key for the item used for internationalization.
iconstringPath to the icon file.
externalbooleanOpen link in new browser tab. Default is false.
linkedSidebars[string]Array of relative paths to sidebar files. This option will add navbar item to sidebar's breadcrumbs. Only effective for top-level navbar items.

Examples

Simple navigation

The following is an example configuration for a simple flat navbar.

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Home
    - page: docs/getting-started.md
      label: Getting Started
    - page: api-reference.yaml
      label: API Reference
    - label: Support
      href: https://support.example.com
      external: true

The following is a screenshot of that navbar.

1 level Navbar

Complete navigation setup

The following example shows a comprehensive navbar configuration for a documentation site with multiple sections, localization support, and external links:

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Home
      labelTranslationKey: nav.home
    - group: Documentation
      groupTranslationKey: nav.docs
      items:
        - page: docs/getting-started.md
          label: Getting Started
          labelTranslationKey: nav.getting-started
        - page: docs/guides/index.md
          label: Guides
          labelTranslationKey: nav.guides
        - page: docs/tutorials/index.md
          label: Tutorials
    - group: API Reference
      items:
        - page: users-api.yaml
          label: Users API
        - page: orders-api.yaml
          label: Orders API
        - page: webhooks-api.yaml
          label: Webhooks API
    - page: changelog.md
      label: Changelog
    - label: Support
      href: https://support.example.com
      external: true
      icon: ./images/support-icon.svg

Multi-product navigation

For sites with multiple products, organize content using groups and linked sidebars:

redocly.yaml
navbar:
  items:
    - page: index.md
      label: Home
    - group: Products
      items:
        - page: product-a/index.md
          label: Product A
          linkedSidebars:
            - product-a/sidebars.yaml
        - page: product-b/index.md
          label: Product B
          linkedSidebars:
            - product-b/sidebars.yaml
    - page: support.md
      label: Support

The following is an example of a dropdown menu with visual separators for better organization:

redocly.yaml
navbar:
  items:
    - group: Products
      items:
        - page: platform/index.md
          label: Platform
        - page: api-gateway/index.md
          label: API Gateway
        - separator: Developer Tools
        - page: cli/index.md
          label: CLI
        - page: sdk/index.md
          label: SDK
    - label: Pricing
      page: pricing.md
    - label: Enterprise
      page: enterprise.md

The following is the visual screenshot of the navbar. Dropdown menu

Hide navbar

To hide the navbar globally or on specific pages:

redocly.yaml
# Hide navbar on all pages
navbar:
  hide: true

Or in page front matter:

---
navbar:
  hide: true
---

Resources