{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migration-guide-developer-portal-110","__idx":0},"children":["Migration guide: Developer portal 1.1.0"]},{"$$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 is a major release that implements the new Reference docs 2.0"," ","features and enhancements for integrated API reference documentation."," ","This migration guide highlights changes that impact the appearance and behavior of your portal,"," ","and provides upgrade instructions for your deployments."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this guide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#migration-guide-developer-portal-110"},"children":["Migration guide: Developer portal 1.1.0"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#new-features"},"children":["New features"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#compatibility-changes"},"children":["Compatibility changes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#renamed-package"},"children":["Renamed package"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#adjust-reference-docs-configuration-options"},"children":["Adjust Reference docs configuration options"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#redocly-cli-integration"},"children":["Redocly CLI integration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#button-component-usage"},"children":["Button component usage"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#default-font-settings"},"children":["Default font settings"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#upgrade-to-developer-portal-110"},"children":["Upgrade to Developer portal 1.1.0"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#continue-using-developer-portal-10x"},"children":["Continue using Developer portal 1.0.x"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-features","__idx":1},"children":["New features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The biggest feature in Developer portal 1.1.0 is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["the integration of Reference docs 2.0"]},". This means that ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/guides/migration-guide-2-0"},"children":["all new features, options, and compatibility changes"]}," from Reference docs 2.0 are included in the Developer portal, and affect the appearance and behavior of integrated API reference documentation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about deprecated options and required changes, refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/guides/migration-guide-2-0#compatibility-changes"},"children":["Compatibility changes section of the Reference docs 2.0 migration guide"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"compatibility-changes","__idx":2},"children":["Compatibility changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These changes break compatibility with previous versions. Adjust your portal settings accordingly before upgrading to prevent build failures after the upgrade."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"renamed-package","__idx":3},"children":["Renamed package"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The package ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/ui"]}," is now deprecated. We recommend you start migrating to the new package ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/developer-portal/ui"]},", as the old one is supported only for a limited time."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"adjust-reference-docs-configuration-options","__idx":4},"children":["Adjust Reference docs configuration options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The new Developer portal uses the new Reference docs package which had some compatibility changes. Adjust settings in all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," files according to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/guides/migration-guide-2-0"},"children":["Reference docs migration guide"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"  type: reference-docs\n  definitionId: petstore\n  settings:\n-   layout:\n-     showNextButton: false\n+   showNextButton: false\n","lang":"diff"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The new Reference docs package introduces a number of new theme knobs. Make sure to adjust some if needed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redocly-cli-integration","__idx":5},"children":["Redocly CLI integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The new Developer portal uses the latest version of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly-cli"]}," package which may detect new errors that were not found by the previous version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To prevent such errors from blocking the portal build, you can either:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["disable some rules in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]}," object"]}," of the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration file"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["or"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/lint#generate-ignore-file"},"children":["create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".redocly.lint-ignore.yaml"]}]}," file to ignore all errors and warnings"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"button-component-usage","__idx":6},"children":["Button component usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specifically, you must make the following changes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Button defaults to the secondary color (used to be primary), adjust where needed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"- <Button> My Button </Button>\n+ <Button color=\"primary\"> My Button </Button>\n","lang":"diff"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transparent"]}," was removed, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["variant=\"outlined\""]}," instead"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"- <Button transparent> My Button </Button>\n+ <Button color=\"primary\" variant=\"outlined\"> My Button </Button>\n","lang":"diff"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inversed"]}," was removed, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["color=\"secondary\""]}," instead"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"- <Button inversed transparent> My Button </Button>\n+ <Button color=\"secondary\" variant=\"outlined\"> My Button </Button>\n","lang":"diff"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["big"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["small"]}," was removed, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}," instead"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"- <Button big> My Button </Button>\n+ <Button color=\"primary\" size=\"large\"> My Button </Button>\n- <Button small> My Button </Button>\n+ <Button color=\"primary\" size=\"small\"> My Button </Button>\n","lang":"diff"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["color"]}," doesn't accept any colors, instead color has to be defined in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.colors"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"- <Button color=\"orange\"> My Button </Button>\n+ <Button color=\"myBrand\"> My Button </Button>\n","lang":"diff"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"colors: {\n    primary: { ... }\n+ myBrand: { main: \"orange\", contrastText: \"#fff\" }\n    ...\n}\n","lang":"diff"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"default-font-settings","__idx":7},"children":["Default font settings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default font family in the Developer portal theme and in the Reference docs theme has changed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["typography.fontFamily='Source Sans Pro, sans-serif'"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default code font family has changed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["typography.code.fontFamily='Source Code Pro, sans-serif'"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you don't have your custom fonts specified in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.ts"]}," or if you want to use these fonts too, you must add the following to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylesheets"]}," section in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"diff","header":{"controls":{"copy":{}}},"source":"  stylesheets:\n+   - https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400,600,700|Source+Code+Pro&display=swap`\n","lang":"diff"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"upgrade-to-developer-portal-110","__idx":8},"children":["Upgrade to Developer portal 1.1.0"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prior to upgrading the portal, access the root directory of your Developer portal project and remove ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yarn.lock"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["node_modules"]}," from it."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the same root directory, access the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.json"]}," file. Open the file and find ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/developer-portal"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@dependencies"]}," section."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Change the version number to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.1.0-beta.28"]}," (or the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/changelog"},"children":["most current version"]},") like in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"  \"dependencies\": {\n  \"@redocly/developer-portal\": \"1.1.0-beta.28\"\n }\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the changes to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.json"]}," file."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yarn install"]}," in the root directory to upgrade your portal."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Installing the new portal version recreates the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yarn.lock"]}," file. Make sure to commit the changes to that file into your version control system. This is a prerequisite for Developer portal projects hosted in Workflows, because it enables Workflows to build your portal with the new version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"continue-using-developer-portal-10x","__idx":9},"children":["Continue using Developer portal 1.0.x"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The last supported version in the Developer portal 1.0.x release channel is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.0.0-beta.162"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We advise all customers to switch to the new Developer portal and upgrade to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.1.0-beta.28"]}," or ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/changelog"},"children":["most current version"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you choose to continue using an older version of the Developer portal, keep in mind that you do not receive security upgrades or new features and improvements. Additionally, you are not able to use the new Reference docs 2.0 for integrated API reference documentation in your portal."]}]},"frontmatter":{"seo":{"title":"Redocly Developer portal 1.1.0 migration guide"},"excludeFromSearch":true},"tagList":["admonition","partial"],"title":"Redocly Developer portal 1.1.0 migration guide","lastModified":"2025-05-28T16:01:32.000Z"}