{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migration-guide-developer-portal-110-beta78","__idx":0},"children":["Migration guide: Developer portal 1.1.0-beta.78"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sidebar-configuration","__idx":1},"children":["Sidebar configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Starting from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The main differences between old and new sidebar configuration are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["New configuration supports multiple ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," files in the portal project. Previously, only one such file was allowed per project."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each sidebar must be configured in its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file. Before, you had to configure all sidebars in one file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file no longer requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebarName"]}," top-level key before listing groups and pages. Previously, this key was required for every configured sidebar."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After upgrading your portal to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.1.0-beta.78"]},", you can start using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-the-new-sidebar-configuration"},"children":["the new configuration"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["(recommended)"]},", or keep ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-the-legacy-sidebar-configuration"},"children":["the legacy configuration"]},"."," ","Note that you may receive warning messages in portal build logs if you decide to keep the legacy configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-new-sidebar-configuration","__idx":2},"children":["Use the new sidebar configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To start using the new sidebar configuration, you must change your existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file to conform to the new configuration syntax."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following changes are required for single sidebar configuration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Remove the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebarName"]}," key from the configuration file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adjust the indentation of all sidebar elements one level up."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare these examples to understand the changes:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Old sidebar","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"firstSidebar:\n  - group: Main group with drilldown style\n    menuStyle: drilldown\n    icon: ./images/custom-icon.png\n    sublabel: Page group with drilldown style\n    pages:\n      - page: developer-portal/commands.md\n        external: true\n      - group: Group level 1\n        menuStyle: drilldown\n        pages:\n          - page: developer-portal/old/component-guide.md\n          - page: developer-portal/advanced/components.md\n            separatorLine: true\n          - page: developer-portal/custom/guides/create-components.md\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"New sidebar","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- group: Main group with drilldown style\n  menuStyle: drilldown\n  icon: ./images/custom-icon.png\n  sublabel: Page group with drilldown style\n  pages:\n    - page: developer-portal/commands.md\n      external: true\n    - group: Group level 1\n      menuStyle: drilldown\n      pages:\n        - page: developer-portal/old/component-guide.md\n        - page: developer-portal/advanced/components.md\n          separatorLine: true\n        - page: developer-portal/custom/guides/create-components.md\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file has multiple sidebars defined, you must create a separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," files into different folders."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It's recommended to place each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file into the folder that contains pages listed in the file."," ","File paths for the pages must be relative to where the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file is placed."," ","If a page is already included in one file, don't include it in any other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," files."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows how to split the legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file into two separate files to configure two sidebars for the portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The main ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file is placed into the root of the project, and the second ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developer-portal/demo"]}," folder."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Old sidebar","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"firstSidebar:\n  - group: Main group with drilldown style\n    menuStyle: drilldown\n    icon: ./images/custom-icon.png\n    sublabel: Page group with drilldown style\n    pages:\n      - page: developer-portal/commands.md\n        external: true\n      - group: Group level 1\n        menuStyle: drilldown\n        pages:\n          - page: developer-portal/old/component-guide.md\n          - page: developer-portal/advanced/components.md\n            separatorLine: true\n          - page: developer-portal/custom/guides/create-components.md\nsecondSidebar:\n  - label: Example page\n    page: developer-portal/demo/example-page.md\n    group: Simple group with default style\n    expanded: false\n    pages:\n      - page: developer-portal/demo/quickstart.md\n        label: Get started with the portal\n      - page: developer-portal/demo/setup.md\n      - page: developer-portal/demo/examples/readme.md\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"New sidebar - main file","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- group: Main group with drilldown style\n  menuStyle: drilldown\n  icon: ./images/custom-icon.png\n  sublabel: Page group with drilldown style\n  pages:\n    - page: commands.md\n      external: true\n    - group: Group level 1\n      menuStyle: drilldown\n      pages:\n        - page: old/component-guide.md\n        - page: advanced/components.md\n          separatorLine: true\n        - page: custom/guides/create-components.md\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":" New sidebar - second file","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- label: Example page\n  page: example-page.md\n  group: Simple group with default style\n  expanded: false\n  pages:\n    - page: quickstart.md\n      label: Get started with the portal\n    - page: setup.md\n    - page: examples/readme.md\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-legacy-sidebar-configuration","__idx":3},"children":["Use the legacy sidebar configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure a sidebar for your portal using the legacy configuration, you must define a custom ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebarName"]}," for it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Under the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebarName"]}," key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label,"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external,"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expanded"]},") assigned to sidebar elements in the file doesn't affect their display order in the portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file with a single configured sidebar"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"sidebarName:\n  - group: Expanded group\n    expanded: true\n    pages:\n      - label: Overview ✅\n        page: developer-portal/overview.md\n      - separator: Navigation\n      - label: Top Nav\n        page: developer-portal/top-navigation.md\n        external: true\n      - page: developer-portal/footer-navigation.md\n        label: Footer Nav\n      - label: Sidebar Nav\n        page: developer-portal/sidebar-nav.md\n  - group: Closed group\n    expanded: false\n    pages:\n      - group: Nested Group with duplicate page\n        expanded: false\n        pages:\n          - page: reference.page.yaml\n            label: API docs example\n          - label: Sidebar Nav - Duplicate\n            page: developer-portal/sidebar-nav.md\n      - label: Quickstart\n        page: developer-portal/quickstart.md\n        separatorLine: true\n      - label: Using Arguments\n        page: developer-portal/arguments.md\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure multiple sidebars for your portal using the legacy configuration, define them in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," configuration file."," ","Each sidebar must have its own, unique top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file with two configured sidebars"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"firstSidebar:\n  - group: Main group with drilldown style\n    menuStyle: drilldown\n    icon: ./images/custom-icon.png\n    sublabel: Page group with drilldown style\n    pages:\n      - page: developer-portal/commands.md\n        external: true\n      - group: Group level 1\n        menuStyle: drilldown\n        pages:\n          - page: developer-portal/old/component-guide.md\n          - page: developer-portal/advanced/components.md\n            separatorLine: true\n          - page: developer-portal/custom/guides/create-components.md\nsecondSidebar:\n  - label: Example page\n    page: developer-portal/example-page.md\n    group: Simple group with default style\n    expanded: false\n    pages:\n      - page: developer-portal/quickstart.md\n        label: Get started with the portal\n      - page: developer-portal/setup.md\n      - page: developer-portal/examples/readme.md\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the preceding example, the first sidebar is identified by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstSidebar"]}," key, and the second by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},"frontmatter":{"seo":{"title":"Redocly Developer portal 1.1.0-beta.78 migration guide"},"excludeFromSearch":true},"tagList":["admonition","partial","tab","tabs"],"title":"Redocly Developer portal 1.1.0-beta.78 migration guide","lastModified":"2025-05-28T16:01:32.000Z"}