Migration guide: Developer portal 1.1.0-beta.78
The developer portal beta is approaching end of life.
Use Realm and Reunite instead. Read the migration guide.
Developer portal 1.1.0-beta.78 introduces changes to sidebar configuration in the portal. This migration guide provides instructions for adjusting configuration files after upgrading your portal.
Sidebar configuration
Starting from the 1.1.0-beta.78 version, the portal supports a new approach to sidebar configuration. We encourage all portal users to switch to this new configuration. Although still supported, the old configuration is deprecated, which means it does not receive updates or bug fixes anymore.
The main differences between old and new sidebar configuration are:
- New configuration supports multiple
sidebars.yamlfiles in the portal project. Previously, only one such file was allowed per project. - Each sidebar must be configured in its own
sidebars.yamlfile. Before, you had to configure all sidebars in one file. - The
sidebars.yamlfile no longer requires thesidebarNametop-level key before listing groups and pages. Previously, this key was required for every configured sidebar.
After upgrading your portal to 1.1.0-beta.78, you can start using the new configuration (recommended), or keep the legacy configuration. Note that you may receive warning messages in portal build logs if you decide to keep the legacy configuration.
Use the new sidebar configuration
To start using the new sidebar configuration, you must change your existing sidebars.yaml file to conform to the new configuration syntax.
The following changes are required for single sidebar configuration:
- Remove the top-level
sidebarNamekey from the configuration file. - Adjust the indentation of all sidebar elements one level up.
Compare these examples to understand the changes:
If your existing sidebars.yaml file has multiple sidebars defined, you must create a separate sidebars.yaml file for each of those sidebars. Treat one of those files as the main configuration file and keep it in the root of your portal project. You must place the other sidebars.yaml files into different folders.
It's recommended to place each sidebars.yaml file into the folder that contains pages listed in the file. File paths for the pages must be relative to where the sidebars.yaml file is placed. If a page is already included in one file, don't include it in any other sidebars.yaml files.
The following example shows how to split the legacy sidebars.yaml file into two separate files to configure two sidebars for the portal.
The main sidebars.yaml file is placed into the root of the project, and the second sidebars.yaml file into the developer-portal/demo folder.
Your developer portal displays one of the configured sidebars contextually, based on the page that's requested. If a page is not included in any of the sidebars, the portal displays it without the sidebar.
Use the legacy sidebar configuration
To configure a sidebar for your portal using the legacy configuration, you must define a custom sidebarName for it in the sidebars.yaml configuration file. You must place the configuration file into the root of your portal project. The sidebar name is not displayed in the portal, and is only used as the unique identifier for the sidebar.
Under the sidebarName key in the sidebars.yaml file, add one or more elements (groups, pages, separators) in the order in which you want to show them in your portal. The order of options (such as label, external, expanded) assigned to sidebar elements in the file doesn't affect their display order in the portal.
Example sidebars.yaml file with a single configured sidebar
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.mdTo configure multiple sidebars for your portal using the legacy configuration, define them in the sidebars.yaml configuration file. Each sidebar must have its own, unique top-level sidebarName key in the configuration file. If a page is already included in one sidebar, don't include it in any other sidebars at the same time.
Example sidebars.yaml file with two configured sidebars
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.md
external: true
- group: Group level 1
menuStyle: drilldown
pages:
- page: developer-portal/old/component-guide.md
- page: developer-portal/advanced/components.md
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.mdIn the preceding example, the first sidebar is identified by the firstSidebar key, and the second by secondSidebar. Your developer portal displays one of the configured sidebars contextually, based on the page that's requested. If a page is not included in any of the sidebars, the portal displays it without the sidebar.