Sidebar configuration

To help your readers access content faster, set up a navigation sidebar for your developer portal. When configured, the sidebar is displayed on the left side of the portal.

You can add the following elements to the sidebar:

To configure your sidebar, modify the sidebars.yaml file in the root of your portal project.

Pay attention to the indentation in YAML files. YAML document structure is determined by indentation, so putting an item on the wrong indentation level can cause build failures. Instead of tabs, always use spaces to indent items in your sidebars.yaml.

To create (or modify) your sidebar in the sidebars.yaml file, start by defining its name. This name is not displayed in the portal, and is only used as the unique identifier for the sidebar.

Under the sidebar name, add one or more elements in order in which you want to show them in the portal. Pages, groups, and separators follow the order defined in the sidebars.yaml file. Generally, the order of options (such as label, external, expanded...) assigned to sidebar elements does not impact how they're displayed.

Important

When a page is linked from the sidebar, it is rendered with the sidebar. Pages that are not included in the sidebar are rendered without the sidebar.

Do not include a page in more than one sidebar. However, you can include it in more than one group in the same sidebar.

Example sidebar structure

sidebarName:
  - group: Expanded group
    expanded: true
    pages:
      - label: Overview ✅
        page: developer-portal/overview.md
      - separator: Navigation
      - label: Top Nav
        page: developer-portal/top-navigation.md
        external: true
      - page: developer-portal/footer-navigation.md
        label: Footer Nav
      - label: Sidebar Nav
        page: developer-portal/sidebar-nav.md
  - group: Closed group
    expanded: false
    pages:
      - group: Nested Group with duplicate page
        expanded: false
        pages:
          - page: reference.page.yaml
            label: API docs example
          - label: Sidebar Nav - Duplicate
            page: developer-portal/sidebar-nav.md
      - label: Quickstart
        page: developer-portal/quickstart.md
        separatorLine: true
      - label: Using Arguments
        page: developer-portal/arguments.md
anotherSidebar:
  - separator: Another separator
  - page: developer-portal/date-range.md

Pages

Your sidebar can contain links to pages within your portal project. Use the page key followed by the relative path to an MD(X) file.

Add MD(X) pages to the sidebar

exampleSidebar:
  - page: developer-portal/quickstart.md
  - page: developer-portal/index.mdx

Pages support the external option that makes them open in a new browser tab or window. When you specify this option for a page, an indicator icon is displayed in the sidebar to the right of the page title.

Make pages open in a new tab

exampleSidebar:
  - page: developer-portal/quickstart.md
    external: true
  - page: developer-portal/index.mdx
    external: true

You can add multiple pages to the sidebar at once by adding /* at the end of a directory path. This takes all MD and MDX files in the directory and adds them to the sidebar. Pages added in this way are sorted by their filenames in an alphabetical order.

If the directory contains any subdirectories, they are automatically converted into groups. Pages inside each group are again sorted alphabetically by their filenames.

Add directory contents to the sidebar

exampleSidebar:
  - page: developer-portal/example-directory/*

Keep in mind that this option does not work like a regular expression pattern matcher. Trying to use it as page: developer-portal/example-directory/a* will not include only files starting with the letter a. It can only be used to include entire (sub)directories, not specific files.

API reference documentation

To link to API reference documentation from the sidebar, provide the relative path to the .page.yaml file associated with the OpenAPI definition you want to include. The sidebar also supports the external option.

Add API reference docs to the sidebar

exampleSidebar:
  - page: developer-portal/openapi/reference.page.yaml
    external: true

The .page.yaml file contents influence how the the OpenAPI definition is presented in the sidebar.

Example reference.page.yaml file

type: reference-docs
definitionId: petstore
settings:
  pagination: section
  showConsole: true
  generateCodeSamples:
    languages:
      - lang: JavaScript
        label: JS
      - lang: Python
  hideDownloadButton: true

For more details, refer to the Integrating API reference page.

Tip

An option similar to /* for MD(X) pages can be used with API reference documentation. Instead of including multiple OAS files, it controls the nesting level of API reference docs in the sidebar. Read our API discovery blog post for examples on how to use this option.

Separators

Separators are useful for indicating section breaks or categorizing content in your sidebar without creating nested groups. They are static, non-interactive sidebar elements, and you cannot select, expand or collapse a separator.

The sidebar supports two separator types, and you can use both as many times as you want in the same sidebar:

  • textual separator
  • line separator

To insert a textual separator, add separator: Custom text as a standalone item between two pages or groups.

Add a textual separator

exampleSidebar:
  - page: developer-portal/quickstart.md
  - separator: This is a separator
  - page: developer-portal/index.mdx

To insert a line separator, add separatorLine: true as an option assigned to a page or to a group. When assigned to a group, it is displayed after the last item in that group.

Add a line separator

exampleSidebar:
  - page: developer-portal/quickstart.md
    separatorLine: true
  - group: Group with separator
    expanded: true
    separatorLine: true
    pages:
      - label: Index
        page: developer-portal/index.mdx
      - label: Glossary
        page: developer-portal/reference/glossary.md

Labels

Labels let you create optional custom titles for pages in the sidebar. By default, if a page is linked without a label, the sidebar will use the title from the linked file. Assigning a label to a page overrides this default behavior.

Add labels to pages

exampleSidebar:
  - page: developer-portal/quickstart.md
    label: Get started with the portal
  - separator: This is a separator
  - label: API reference docs
    page: developer-portal/openapi/reference.page.yaml

The display order of pages in the sidebar is not affected if you set the label first and page second, or vice versa.

Groups

Use groups to organize pages into a nested navigation structure. Each group can contain any number of pages, separators, and other (nested) groups. While there are no theoretical limits on nesting, there are practical limits to keeping the documentation easy to navigate for your readers.

Groups are dynamic, interactive sidebar elements. You can control the default behavior of each group with the expanded option.

Option Description
expanded: true The pages will be open (expanded) when the page loads.
expanded: false The pages will be collapsed when the page loads.
expanded: always The pages will be open (expanded) and cannot be collapsed.

There are two ways to create a group in the sidebar:

  1. As a simple navigation item (expands, but does not link to any content when selected)
exampleSidebar:
  - group: Simple group name
    expanded: true
    selectFirstItemOnExpand: true
    pages:
      - page: developer-portal/quickstart.md
        label: Get started with the portal
      - separator: Commands
      - page: developer-portal/commands.mdx

You can use the selectFirstItemOnExpand option to automatically open the first item in the group when you select the group name in the sidebar. This option must not be used together with page (which makes the group behave as an expandable page).

  1. As an expandable page (when selected, loads the contents of a page and expands to show nested pages)
exampleSidebar:
  - group: Page group name
    page: developer-portal/example-page.md
    expanded: true
    pages:
      - page: developer-portal/quickstart.md
        label: Get started with the portal
      - separator: Commands
      - page: developer-portal/commands.mdx

Changing the nesting level in the sidebar does not affect the URLs of your pages. Groups are unrelated to original file paths, so your sidebar organization does not have to mirror the folders and subfolders in your project. For example, if your configuration guides are scattered into different folders, you can still link them in the same sidebar group.

Create deep nesting levels

exampleSidebar:
  - group: Main group
    page: developer-portal/example-page.md
    expanded: always
    pages:
      - page: developer-portal/quickstart.md
        label: Get started with the portal
      - group: Group level 1
        expanded: true
        pages:
          - page: developer-portal/commands.mdx
            label: Commands
          - separator: Components
          - page: developer-portal/old/component-guide.md
          - page: developer-portal/advanced/components.mdx
          - page: developer-portal/custom/guides/create-components.md
          - group: Group level 2
            expanded: false
            pages:
              - page: developer-portal/advanced.md
                external: true

By default, the sidebar is displayed as a tree-view hierarchy. All top-level navigation items are visible even when you expand deeply nested groups.

Default sidebar view

We also support an alternative sidebar style called drilldown. With this style, the sidebar uses a scoped view for groups. Instead of displaying each group as an expanded tree in a big list of items, it leads you to a separate "page" within the sidebar (the scope for the selected group).

The back button is automatically displayed at the top of the current scope, above the group name, so you can quickly return to the previous scope. Group names and separator names use bold text by default in the drilldown style.

Drilldown sidebar view

To enable the drilldown style, specify it for one or more groups in your sidebar. You can use the default style and the drilldown style for different groups in the same sidebar.

Note the differences in supported options for sidebar styles:

  • only in drilldown: icon (optional custom icon to the left of the group name) and sublabel (optional description text under the group name)
  • only in default: expanded (automatically collapse or expand the group on page load)

Use the drilldown sidebar style

exampleSidebar:
  - group: Main group
    page: developer-portal/example-page.md
    menuStyle: drilldown
    icon: ./images/custom-icon.png
    sublabel: The main group containing all pages
    pages:
      - group: Nested drilldown group
        menuStyle: drilldown
        icon: ./images/components.png
        sublabel: Learn more about components
        pages:
          - page: developer-portal/old/component-guide.md
            label: Understanding components
          - page: developer-portal/advanced/components.mdx
            external: true
          - page: developer-portal/custom/guides/create-components.md
            label: Create your own component
            separatorLine: true
      - group: Nested default group
        expanded: false
        pages:
          - page: developer-portal/advanced.md
            external: true
          - separator: This is a separator
          - page: developer-portal/commands.md
            label: Advanced commands
      - page: reference.page.yaml

Set up multiple sidebars

The most common approach for portals is to configure a single sidebar for your developer portal. However, the sidebars.yaml file supports multiple sidebar navigation schemes, allowing you to set up different sidebars.

Each sidebar must have its own, unique top-level key in the sidebars.yaml file. If a page is already included in one sidebar, do not include it in any other sidebars at the same time.

You can use default and drilldown styles in all your sidebars. If you decide to theme the sidebar, remember the configured theming options will apply to all sidebars.

Use multiple sidebars in the portal

firstSidebar:
  - group: Main group with drilldown style
    menuStyle: drilldown
    icon: ./images/custom-icon.png
    sublabel: Page group with drilldown style
    pages:
      - page: developer-portal/commands.mdx
        external: true
      - group: Group level 1
        menuStyle: drilldown
        pages:
          - page: developer-portal/old/component-guide.md
          - page: developer-portal/advanced/components.mdx
            separatorLine: true
          - page: developer-portal/custom/guides/create-components.md
secondSidebar:
  - label: Example page
    page: developer-portal/example-page.md
    group: Simple group with default style
    expanded: false
    pages:
      - page: developer-portal/quickstart.md
        label: Get started with the portal
      - page: developer-portal/setup.md
      - page: developer-portal/examples/readme.md

In the preceding example, the first sidebar is identified by the firstSidebar key, and the second by secondSidebar.

Your developer portal will display one of the configured sidebars contextually, based on the page that is being requested. If a page is not included in any of the sidebars, it is displayed without the sidebar.

Theme the sidebar

You can style some visual aspects of your sidebar by modifying the developer portal theme.

In the root of your portal project, find the theme.ts file and edit the sidebar section within export const theme = {.

Example sidebar customization in theme.ts

  sidebar: {
  	backgroundColor: '#d6eaf8',
  	activeBgColor: ' #3349ff',
    width: '300px',
  	textColor: '#000000',
  	textColorSecondary: '#239b56',
  	activeTextColor: '#ffffff',
  	separatorLineColor: '#e67e22',
  	separatorLabelColor: '#e67e22',
  	rightLineColor: '#1e8449',
  	caretColor: '#1e8449',
  	fontFamily: '"Source Sans Pro", sans-serif',
  	fontSize: '14px',
  	spacing: {
  	  unit: 10,
  	  paddingHorizontal: 5,
  	  paddingVertical: 5
  	}

Drilldown sidebar with custom theming options

Supported sidebar theming options

Note that some theming options apply only to the drilldown sidebar style.

Option Type Description
backgroundColor string Changes the background color of the entire sidebar section.
activeBgColor string Changes the background color of the active item (currently selected item) in the sidebar.
width string Controls the width of the entire sidebar section.
textColor string Changes the text color of default sidebar items (page names, page labels, group names).
textColorSecondary string Changes the text color of drilldown sidebar items (group sublabels and scope links).
activeTextColor string Changes the text color of the active item (currently selected item) in the sidebar.
separatorLineColor string When the separator is used as a horizontal line, this option controls its color.
separatorLabelColor string When the separator is used as text, this option controls its color.
rightLineColor string Changes the color of the vertical line dividing the sidebar section from the page contents.
caretColor string Controls the color of the back button (<-) in drilldown style, and the V button for expanding groups.
fontFamily string Changes the font family of all text in the sidebar.
fontSize string Changes the font size of all text in the sidebar. Can be provided in any of the standard units (px, em, rem...).
borderRadius string Controls the border radius of the item. Default value is 4px. Can be provided in any of the standard units (px, em, rem...).
spacing object Controls the spacing of items in the sidebar. The numbers set here are used to calculate the final positioning value of each item (in px).
spacing.unit number Controls the value for: textual separator margin-left; menu item margin-left; back button margin-right; drilldown menu icon width, height, and margin-right; version switcher padding.
spacing.paddingHorizontal number Controls the value for horizontal spacing of items in the sidebar (textual separator padding; menu item padding-right and padding-left).
spacing.paddingVertical number Controls the value for vertical spacing of items in the sidebar (textual separator padding; line separator margin; menu item padding-top and padding-bottom; back button margin-bottom).
spacing.offsetLeft number Controls the value for left offset of items in the sidebar. Default value is sidebar.spacing.unit * 2.
spacing.offsetNesting number Controls the value for nesting offset of items in the sidebar. Each nested group will have this offset. Default value is sidebar.spacing.unit * 2.
spacing.offsetTop number Controls the value for top offset, which is the distance between the top of the sidebar and the first item. Default value is sidebar.spacing.unit * 2.