From cd551339de7c32627fa946ca9d5f787426735d8c Mon Sep 17 00:00:00 2001 From: JLekawa Date: Fri, 20 Mar 2026 13:10:03 +0100 Subject: [PATCH 1/7] docs(realm): add redirects to migrate files --- redirects.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/redirects.yaml b/redirects.yaml index d4f79d57..b6cae8d8 100644 --- a/redirects.yaml +++ b/redirects.yaml @@ -768,3 +768,11 @@ to: '/docs/realm/access/rbac' '/docs/realm/setup/concepts/roles': to: '/docs/realm/access/roles' + +# Redirects after moving migration files + +'/docs/realm/get-started/migrate-from-legacy-portal': + to: '/docs/realm/get-started/migrate/migrate-from-legacy-portal' +'/docs/realm/get-started/migrate-api-reference': + to: '/docs/realm/get-started/migrate/migrate-api-reference' + From 64e2cf8d23c4edcf0c48ce8b9270d4c5ef944e8f Mon Sep 17 00:00:00 2001 From: JLekawa Date: Fri, 3 Apr 2026 17:04:25 +0200 Subject: [PATCH 2/7] docs(other): move migration docs to legacy --- .../migrate-from-legacy-portal.md | 1132 +++++++++++++++++ .../use-legacy-ui-components.md | 176 +++ docs-legacy/workflows/migrate-api-refernce.md | 291 +++++ 3 files changed, 1599 insertions(+) create mode 100644 docs-legacy/developer-portal/migrate-from-legacy-portal.md create mode 100644 docs-legacy/developer-portal/use-legacy-ui-components.md create mode 100644 docs-legacy/workflows/migrate-api-refernce.md diff --git a/docs-legacy/developer-portal/migrate-from-legacy-portal.md b/docs-legacy/developer-portal/migrate-from-legacy-portal.md new file mode 100644 index 00000000..1104f2fe --- /dev/null +++ b/docs-legacy/developer-portal/migrate-from-legacy-portal.md @@ -0,0 +1,1132 @@ +# Migrate from legacy portal + +This guide was created for users of Redocly's developer portal product. +It contains steps, information, and resources to help you migrate an existing developer portal project to use Realm. + +Realm is a flexible, powerful platform for building documentation that empowers authors and delights users. +Realm combines all the features of Redoc, Revel, and Reef into a single offering, from API reference documentation to custom writing elements. + +## Migration overview + +This section provides a high-level overview of the migration process from the legacy portal to Realm. + +### Connect services to Reunite + +At the start of your migration, you'll need to create a project in Reunite and connect remote services to Reunite. + +1. Sign up or log in to your Reunite account. + +2. (Optional) [Add an identity provider](https://www.redocly.com/docs/realm/reunite/organization/sso/add-idp.md) and [configure SSO](https://www.redocly.com/docs/realm/reunite/organization/sso/configure-sso.md). + +3. Go to your [Reunite dashboard](https://app.cloud.redocly.com) and [create a new project](https://www.redocly.com/docs/realm/reunite/project/manage-projects.md#create-a-project). + +4. Go to **Settings** --> **Git hosting** and [connect your existing repository](https://www.redocly.com/docs/realm/reunite/project/connect-git/connect-git-provider.md). + +5. Go to **Editor** to verify that your project files are synced with Reunite. + +Don't worry about errors at this stage. +They'll resolve as you work through the content in this guide. + +### Prepare for migration + +Prepare your project for migration before making changes to content or configuration. + +1. Create a new branch in your remote repository to contain migration changes; for example, your new branch name could be `portal-upgrade`. + +2. On the new branch, create a `migration-test.md` file and open a pull request against your repository's `main` branch. + +3. In Reunite, go to your project's **Settings** --> **Git hosting** and update the connection to use the new migration branch, `portal-upgrade`. + +4. Check the Reunite Editor to verify your new file is present. + +5. (Optional) Depending on your timeline, you may consider [locking your repository](https://docs.github.com/en/migrations/overview/about-locked-repositories) during migration. + +Use the migration branch to preview and test your changes while working through migration. + +### Execute migration + +Migrate your developer portal project to Realm using the content in this guide. + +1. From your migration branch (`portal-upgrade`), create a new branch to work from; for example, your new branch could be named `migrate-sidebar`. + +2. Use this guide to migrate each part of your project. + In this example, that's the [Update sidebar](#update-sidebar) section. + +3. Run the [local Realm preview](#run-local-realm-preview) to see the changes while you work. + +4. Open a pull request in your repository to merge the `migrate-sidebar` branch into `portal-upgrade`. + +5. Review the code and the [branch preview build](https://www.redocly.com/docs/realm/reunite/project/use-previews.md). + +6. (Optional) Explore the other tools in Reunite, such as [visual review](https://www.redocly.com/docs/realm/reunite/project/pull-request/review-pull-request.md#review-visual-and-code-diff). + +7. Merge the pull request into the `portal-upgrade` branch to deploy it to the Reunite "production" build. + +Using the migration to mimic a workflow similar to the one you'll use in production will help build familiarity with the new tools. + +### Publish migrated project + +Once the content is migrated and you're ready to "go live" with the new project + +1. Go to your Git provider and [suspend](https://docs.github.com/en/apps/maintaining-github-apps/suspending-a-github-app-installation) the Redocly Workflows app. + +2. In Reunite, go to the project's **Settings** --> **Git hosting** and update the connection to use the `main`, or production, branch of your repository. + +3. Merge your migration branch, `portal-upgrade`, into your production branch, `main`. + +4. Review the production deployment of the site to ensure it's ready for release. + +5. In Reunite, [set a custom domain](https://www.redocly.com/docs/realm//reunite/project/custom-domain.md) for your project. + +6. Update your CNAME record to point to `ssl.redocly.app`. + This change can take up to 8 hours to propagate depending on your provider. + +7. (Optional) [Delete](https://docs.github.com/en/apps/maintaining-github-apps/deleting-a-github-app) or deactivate the Redocly Workflows app in your Git provider. + +Congratulations! +Your documentation is migrated and deployed on Redocly's latest and greatest product. + +## Migration helper script + +To help with the migration process, we created a [migration helper script](https://github.com/redocly-demo/migrate-portal) that can automate many of the syntax changes required during migration. +This script can save you time and reduce the likelihood of manual errors. + +{% admonition type="warning" name="Work in progress" %} + The migration script is _experimental_ and may crash or produce unexpected results. + Please contact us or open an issue if that occurs. +{% /admonition %} + +### Use migration script + +1. Open your project to the migration branch (i.e. + `portal-upgrade`). + +2. Remove the `node_modules` folder. + +3. Run the following command to install and execute the script: `npm exec github:redocly-demo/migrate-portal`. + +4. Navigate the script prompts. +The script analyzes your project files and automatically make the necessary syntax changes. + +5. Review the `_MIGRATION.md` file and make additional changes as needed. + +6. Test your project to ensure everything works as expected. + +### Limitations of script + +The migration script is a useful tool, but it's important to note: + +- It may not catch _all_ necessary changes, especially for highly customized projects. +- It doesn't handle MDX to Markdoc conversions or custom components. +- Manual review and testing is _still required_ after running the script. + +The script is a great starting point, but it's **not a complete replacement for manual migration work**. +Always review the changes made by the script and refer to the rest of this migration guide for a more comprehensive update to your project. + +## Migrate portal project + +This section covers the specific steps and changes needed for your project during migration. + +### Run local Realm preview + +During migration, use the local development preview of Realm to experience the documentation as an end user would. +This helps build familiarity with Realm and learn about error behaviors. + +Follow the steps below to configure your project to run local Realm previews: + +1. Remove "developer-portal" from your npm modules: `npm uninstall --save @redocly/developer-portal` + +2. Add the Realm library: `npm install --save @redocly/realm` + +3. Clear your project's cache: `rm -rf node_modules && rm -rf package-lock.json && npm install` + +4. In your `package.json` file, add a script that runs the Redocly CLI preview command: + + ```{% title="package.json" %} + ... + "scripts": { + "start": "npx @redocly/cli preview", + }, + ... + ``` + +Now you can use the following command to run a local Realm preview: `npm run start`. +Use this preview to review the changes you make during migration. + +### Migrate content + +Realm contains a major change to content creation: MDX is replaced with [Markdoc](https://redocly.com/learn/markdoc). +That means authors continue writing in Markdown, but, when they need to add a custom element or component, they use Markdoc syntax _instead of MDX_. + +With the exception of MDX, Realm supports the same types of content as the developer portal while adding support for new content, such as AsyncAPI, GraphQL, and React pages. + +#### Update API reference + +Realm includes the redesigned version of Redoc, which powers the API reference documentation. +There are changes to how API descriptions are integrated and configured in your project. + +##### API descriptions as remote content + +In Realm, the way _externally-managed_ API descriptions are used in your project has changed. + +- The `oasDefinitions` property is replaced by `apis`. +- API descriptions (or copies of them) must be **stored in the project files**. + - Using a remote URL or snapshot URL in the configuration file is no longer supported. + +During migration, set up [remote content](https://www.redocly.com/docs/realm/reunite/project/remote-content/remote-content.md) connections for any externally-maintained API descriptions. + +The following example shows the old and new syntax for using remote API descriptions: + +{% tabs %} + {% tab label="Old remote descriptions"%} + + In this example, the `siteConfig.yaml` file uses direct pointers to the remote API definitions. + + ```yaml {% title="siteConfig.yaml" %} + oasDefinitions: + art-museum: https://api.redoc.ly/registry/bundle/art-museum/1.2.1/art-museum-openapi.yaml?branch=main + flight-museum: https://example.com/flight-museum/main/flight-museum-openapi.yaml + ``` + + {% /tab %} + {% tab label="New remote descriptions"%} + + In this example, both API definitions are set up as remote content sources and the `redocly.yaml` file uses relative file paths. + + - The art-museum uses [remote content from GitHub](../../reunite/project/remote-content/from-github.md). + - The flight-museum uses [remote content from a URL](../../reunite/project/remote-content/url.md). + + ```yaml {% title="redocly.yaml" %} + apis: + art-museum@main: + root: art/art-museum-openapi.yaml + flight-museum@v1: + root: flight/flight-museum-openapi.yaml + ``` + + {% /tab %} +{% /tabs %} + +##### Centralized API reference configuration + +In Realm, configuring the default API reference settings remains the same (using `openapi`), but configuring the API reference for multiple API definitions has changed. + +Creating multiple per-definition configurations now happens in the `redocly.yaml` configuration file. +Using `*.page.yaml` files to manage configuration is no longer supported. + +During migration, move all API definition configuration into the Redocly configuration file. + +The following example shows the old and new syntax for configuring multiple API definitions: + +{% tabs %} + {% tab label="Old multi config"%} + + ```yaml {% title="art/art-museum.page.yaml" %} + type: reference-docs + definitionId: art-museum + settings: + hideDownloadButtons: true + codeSamples: + skipOptionalParameters: true + languages: + - lang: 'curl' + label: 'cURL' + ``` + + ```yaml {% title="flight/flight-museum.page.yaml" %} + type: reference-docs + definitionId: flight-museum + settings: + hideDownloadButtons: false + hideSchemaTitles: true + codeSamples: + skipOptionalParameters: false + languages: + - lang: 'JavaScript' + label: 'JS' + ``` + + {% /tab %} + {% tab label="New multi config"%} + + ```yaml {% title="redocly.yaml" %} + apis: + art-museum@main: + root: art/art-museum-openapi.yaml + openapi: + hideDownloadButtons: true + codeSamples: + skipOptionalParameters: true + languages: + - lang: 'curl' + label: 'cURL' + flight-museum@v1: + root: flight/flight-museum-openapi.yaml + openapi: + hideDownloadButtons: false + hideSchemaTitles: true + codeSamples: + skipOptionalParameters: false + languages: + - lang: 'JavaScript' + label: 'JS' + ``` + + {% /tab %} +{% /tabs %} + +When multiple APIs are configured, Realm and Reef users can also use the API catalog feature. + +##### Migrate the API catalog + +Realm and Reef users have access to the built-in API catalog feature, which is used to organize and display multiple API definitions, making them more discoverable for users. + +- In the developer portal, the API catalog had to be _added as a custom component_ in an MDX page. +- In Realm, the classic catalog feature is already _built into the product_ and is enabled through configuration. + +Use the following guide to enable the classic catalog during your migration: [configure a classic catalog in your project](https://www.redocly.com/docs/realm/config/catalog-classic.md). + +#### Update Markdown files + +Markdown is fully supported in Realm. +That means Markdown files used in the developer portal will render the same elements on a page in Realm. +However, some specific features may require adjustments during migration. + +##### Change admonition syntax + +Realm adds Markdoc tags for [admonitions](https://redocly.com/docs/learn-markdoc/tags/admonition). +The Markdown syntax for admonitions, `:::`, is no longer supported. + +During migration, replace all Markdown admonitions with Markdoc tags. +Use this [gist for converting admonition syntax](https://gist.github.com/adamaltman/7eb066430369135ef2b96605fd0c7d85) if you'd like to update them all at once. + +The following example shows the old and new admonition syntax: + +{% tabs %} + {% tab label="Old admonition syntax" %} + ```markdown + :::info Optional title + + Just FYI + + ::: + ``` + {% /tab %} + {% tab label="New admonition syntax" %} + ```markdown {% process=false %} + {% admonition type="info" name="Optional title" %} + Just FYI + {% /admonition %} + ``` + {% /tab %} +{% /tabs %} + +##### Change reusable snippets + +Realm adds a Markdoc tag for [partials](https://redocly.com/docs/learn-markdoc/tags/partial), which is a big upgrade for working with [reusable content](https://www.redocly.com/docs/realm/content/markdoc-tags/partial.md). +The developer portal's approach to reusable content, which used Markdown snippets in an HTML `` tag, is no longer supported. + +During migration, replace any embedded Markdown snippets with the new partials tag, as in the following example: + +{% tabs %} + {% tab label="Old reusable content" %} + ```markdown {% process=false %} + # Example page + + Follow the steps below before starting this tutorial: + + + ``` + {% /tab %} + {% tab label="New reusable content" %} + ```markdown {% process=false %} + # Example page + + Follow the steps below before starting this tutorial: + + {% partial file="_snippets/tutorial/common-setup-snippet.md" /%} + ``` + {% /tab %} +{% /tabs %} + +##### Change code fence titles + +In Realm, titles are added to code fences using Markdoc tag syntax, replacing the title syntax used in the developer portal. + +During migration, update all code fences with a title to use Markdown tag syntax, as in the following example: + +{% tabs %} + {% tab label="Old fence title"%} + + ~~~markdown + ```python example.py + def hello_world(): + print("Hello, World!") + + hello_world() + ``` + ~~~ + + {% /tab %} + {% tab label="New fence title"%} + + {% markdoc-example %} + ~~~markdown {% process=false %} + ```python {% title="example.py" %} + def hello_world(): + print("Hello, World!") + + hello_world() + ``` + ~~~ + {% /markdoc-example %} + + {% /tab %} +{% /tabs %} + + +##### Change tabbed code samples + +Realm adds a Markdoc tag for [tabs](https://redocly.com/docs/learn-markdoc/tags/tabs) that supports all content types. +Tabbed code sample syntax from the developer portal needs to be updated. + +During migration, update all tabbed code samples to use the `tabs` tag. +If custom tab names are required, use the nested `tag` element. + +The following example shows the old syntax, new syntax, and new syntax with custom labels: + +{% tabs %} + + {% tab label="Old code tabs" %} + + ~~~ + ```javascript + javascript; + ``` + + ```python + python + ``` + + ```java title + example text + ``` + + ```custom tab name + example text + ``` + ~~~ + {% /tab %} + + {% tab label="New code tabs" %} + + Note that 'custom tab name' will break because of the spaces. + Use named tabs instead. + + {% markdoc-example %} + + ~~~ {% process=false %} + {% tabs %} + ```javascript + javascript; + ``` + + ```python + python + ``` + + ```java title + example text + ``` + + ```custom tab name + example text + ``` + {% /tabs %} + ~~~ + {% /markdoc-example %} + {% /tab %} + + {% tab label="New named tabs"%} + {% markdoc-example %} + ~~~ {% process=false %} + {% tabs %} + {% tab label="javascript tab" %} + ```javascript + javascript; + ``` + {% /tab %} + {% tab label="python tab" %} + ```python + python + ``` + {% /tab %} + {% tab label="java tab" %} + ```java title + example text + ``` + {% /tab %} + {% tab label="example tab name" %} + ```custom tab name + example text + ``` + {% /tab %} + {% /tabs %} + ~~~ + {% /markdoc-example %} + {% /tab %} +{% /tabs %} + +##### Change page-level redirects + +Realm uses a different format for the redirects defined in a page's front matter. + +During migration, update front matter redirects to use the new format, as in the following example: + +{% tabs %} + {% tab label="Old front matter redirect" %} + ```markdown {% process=false %} + --- + redirectFrom: + - /docs/api-reference/on-premise/license-key/ + - /another-example-page/ + - /2020/12/example-blog-post/ + --- + + # Example H1 under front matter + ``` + {% /tab %} + {% tab label="New front matter redirect"%} + ```markdown {% process=false %} + --- + redirects: + '/docs/api-reference/on-premise/license-key/': {} + '/another-example-page/': {} + '/2020/12/example-blog-post/': {} + --- + + # Example H1 under front matter + ``` + {% /tab %} +{% /tabs %} + +#### Update MDX files + +MDX files _do not render in Realm_ because support for MDX was removed in favor of [Markdoc](https://markdoc.dev/), which offers the same code-in-content capabilities of MDX, but is optimized for _authoring experience_. + +During migration, you need to update your MDX files for their content to render. + +For **MDX files without Markdown**, change their file extension to `.page.tsx` to [create a React page](https://www.redocly.com/docs/realm/customization/create-react-page.md). +As long as the imports are correct, those files can serve as pages in Realm. + +For **MDX files that combine Markdown and JSX**, use the following steps to update the file and make it compatible with Realm: + +1. Change the filetype from `.mdx` to `.md`. + +2. Remove the JSX syntax from the file. + Alternatively, you can comment it out and use it to [create a tag](#create-markdoc-tags-from-jsx) later. + + ```markdown {% title="product-guide.mdx" %} + import { ProductGallery } from './components/ProductGallery.tsx' + + # Product overview + + Click a product from the gallery below to open a modal with more information. + + + ``` + +3. (Optional) Remove or comment out the import statements. + +Converting the filetype to Markdown and removing the JSX will allows Realm to render the _Markdown_ content from the migrated MDX files. +However, rendering the JSX element requires additional work. + +You can [use the legacy UI components](./use-legacy-ui-components.md) to help with migration, but we recommend replacing them. + +##### Change OpenApiTryIt component + +Realm contains an upgraded replacement to the "Try it console" called Replay, which allows users to send API requests from your documentation. + +Realm adds a [Markdoc tag for Replay](https://redocly.com/docs/learn-markdoc/tags/replay-openapi) that can embed the Replay console in a Markdown file. +The `OpenApiTryIt` component is no longer supported. + +During migration, change all implementations of OpenApiTryIt to use the `replay-openapi` Markdoc tag. +Use the same OpenAPI description as the source. + +The following example shows the same operation and configuration implemented in the Try it (old) and Replay (new) syntax: + +{% tabs %} + {% tab label="Old Try it syntax"%} + + ```javascript + + ``` + + {% /tab %} + + {% tab label="New Replay syntax"%} + {% markdoc-example %} + ``` {% process=false %} + {% replay-openapi + descriptionFile="../../openapi/museum-api.yaml" + operationId="listSpecialEvents" + parameters={ + query: { + limit: 10 + }, + header: { + exampleKey: "exampleValue" + } + } + /%} + ``` + {% /markdoc-example %} + {% /tab %} +{% /tabs %} + +Note that the Try it component used a `definitionId` property to reference a description, but the Replay tag uses a `descriptionFile` property with a path. + +##### Create Markdoc tags from JSX + +
+ Learn how MDX and Markdoc are different + + Markdoc enforces a strict separation of code and content. + Although MDX and Markdoc both enable authors to use custom components with Markdown, there's a fundamental difference in structure: + +- With MDX, authors use JSX syntax to add custom components directly. +- With Markdoc, authors use Markdoc tags, which have a defined schema and control the rendering of the custom component. + + See [Write with Markdoc](https://redocly.com/docs/learn-markdoc/write-with-markdoc) for a deeper explanation of using Markdoc as a technical writer. +
+ +You can create Markdoc tags using the JSX from the MDX files to make them available to authors. +Authors can use those custom elements in their writing using the Markdoc tag syntax. + +During migration, you can create Markdoc tags from JSX using the following steps: + +1. Copy the JSX from the migrated file. + +2. Add it as a custom component. + For example, `@theme/markdoc/components/YourComponent.tsx`. + +3. Export the component from `@theme/markdoc/components.tsx`. + +4. Define the Markdoc tag schema, `@theme/markdoc/components/YourComponent-Schema.ts`. + +5. Export the tag from `@theme/markdoc/schema.ts`. + +Now authors can use the Markdoc tag to render the same element from the migrated JSX. + +{% admonition type="info" %} + This section explains the process for migrating custom elements. + For more detailed guidance on creating tags, see See [Build a Markdoc tag](https://www.redocly.com/docs/realm/customization/build-markdoc-tags.md). +{% /admonition %} + +### Migrate navigation + +Realm has made improvements and changes to the tools that help users navigate your website. +Use the sections below to migrate your navigation configuration and its compatible with Realm. + +#### Update navbar + +Settings for the [navigation bar](https://www.redocly.com/docs/realm/config/navbar.md) have changed. + +During migration, update your navbar configuration to reflect the following changes: + +- The `nav` property was renamed and moved to `navbar`. +- Navbar entries must be listed in an `items` property. +- The `search` property was removed from navbar config and added as a [search option](https://www.redocly.com/docs/realm/config/search.md). +- A new option called `linkedSidebar` can add a navbar item to the breadcrumbs of top-level sidebar entries. + +The following example shows a navbar configuration updated to work with Realm: + +{% tabs %} + {% tab label="Old navbar syntax"%} + ```yaml {% title="siteConfig.yaml" %} + nav: + - label: Home + page: index.md + - label: Link with icon + page: example-page.md + icon: images/page-icon.png + - label: Redocly docs + href: 'https://redocly.com/docs' + - search: false + ``` + {% /tab %} + {% tab label="New navbar syntax"%} + ```yaml {% title="redocly.yaml" %} + navbar: + items: + - label: Home + page: index.md + - label: Link with icon + page: example-page.md + icon: images/page-icon.png + - label: Redocly docs + href: 'https://redocly.com/docs' + search: + hide: true + ``` + {% /tab %} +{% /tabs %} + +#### Update footer + +Settings for the [footer](https://www.redocly.com/docs/realm/config/footer.md) have some small but structural changes. + +During migration, update your footer configuration to reflect the following changes: + +- The `footer` property was moved to `footer`. +- The `columns` property was renamed to `items`. + +The following example the same footer settings using the old and new syntax: + +{% tabs %} + {% tab label="Old footer syntax"%} + ```yaml {% title="siteConfig.yaml" %} + footer: + copyrightText: Copyright © Example page + columns: + - group: Legal + items: + - label: Terms of Use + href: 'https://example.com/terms' + - label: Privacy Notice + href: 'https://example.com/privacy' + external: true + - group: Support + items: + - label: FAQ + page: developer-portal/faq.md + permission: read-docs + - label: Contact us + page: developer-portal/contact.mdx + external: true + ``` + {% /tab %} + {% tab label="New footer syntax"%} + ```yaml {% title="redocly.yaml" %} + footer: + copyrightText: Copyright © Example page + items: + - group: Legal + items: + - label: Terms of Use + href: 'https://example.com/terms' + - label: Privacy Notice + href: 'https://example.com/privacy' + external: true + - group: Support + items: + - label: FAQ + page: developer-portal/faq.md + permission: read-docs + - label: Contact us + page: developer-portal/contact.mdx + external: true + ``` + {% /tab %} +{% /tabs %} + +#### Update sidebar + +New settings and features were added to the [sidebar](https://www.redocly.com/docs/realm/navigation/sidebars.md). + +During migration, update your sidebar configuration to reflect the following changes: + +- Links to MDX pages are no longer supported. +- The `pages` property is replaced by `items` in sidebar groups. + +The following example shows the same sidebar configuration using old and new syntax: + + {% tabs %} + {% tab label="Old sidebar syntax"%} + ```yaml {% title="sidebars.yaml" %} + - group: Awesome sidebar group + icon: ./images/custom-icon.png + pages: + - page: index.md + label: Home page + - page: pricing-page.mdx + label: Pricing page + - href: https://redocly.com/docs/ + label: Redocly docs + ``` + {% /tab %} + {% tab label="New sidebar syntax"%} + ```yaml {% title="sidebars.yaml" %} + - group: Awesome sidebar group + icon: ./images/custom-icon.png + items: + - page: index.md + label: Home page + - page: pricing-page.md + label: Pricing page + - href: https://redocly.com/docs/ + label: Redocly docs + ``` + {% /tab %} + {% /tabs %} + +After your sidebar config works with Realm, explore the following new sidebar features: + +- Build sidebars using configuration from [multiple files](https://www.redocly.com/docs/realm/navigation/sidebars.md#add-multiple-sidebars) using fragments. +- [Add a sidebar to a single page](https://www.redocly.com/docs/realm/navigation/sidebars.md#add-a-sidebar-to-a-single-page) to show the sidebar on a page without listing it on `sidebars.yaml`. +- Control the visibility of [sidebar entries with RBAC](https://www.redocly.com/docs/realm/access/links-and-groups-permissions.md#in-the-sidebar). + +### Migrate configuration + +The configuration options have changed in Realm. +New options were added for Realm, but many of the existing options for the developer portal have moved, changed, or been deprecated. + +During migration, follow the steps below to migrate your project configuration: + +1. Rename the `siteConfig.yaml` file to `redocly.yaml`. +2. Update your configuration to reflect the changes in the table below. +3. Test the configuration in Realm and work through any errors. +4. After migration, explore and add [new configuration options](https://www.redocly.com/docs/realm/config). + +The following table summarizes the changes to the configuration options for the developer portal: + +{% table %} + +- Legacy config option +- Change in Realm + +--- + +- `analytics` +- Moved to `analytics`. + +--- + +- `copyCodeSnippet` +- Replaced by `codeSnippet`. + New features added, see [codeSnippet](https://www.redocly.com/docs/realm/config/code-snippet.md). + +--- + +- `disableLastModified` +- Replaced by `markdown.lastUpdatedBlock`. + New features added, see [last updated object](https://www.redocly.com/docs/realm/config/markdown.md#last-updated-object). + +--- + +- `editPage` +- Moved to `markdown.editPage`. + +--- + +- `footer` +- Moved to `footer`. + New syntax and features, see [footer](https://www.redocly.com/docs/realm/config/footer.md). + +--- + +- `logo` +- Moved to `logo`. + Now supports light mode / dark mode versions. + +--- + +- `nav` +- Replaced by `navbar`. + New syntax and features, see [navbar options](https://www.redocly.com/docs/realm/config/navbar.md) or [update navbar](#update-navbar). + +--- + +- `oasDefinitions` +- Replaced by `apis`. + Syntax changes, see [apis](https://redocly.com/docs/cli/configuration/reference/apis). + +--- + +- `scripts` +- Must specify script tag location, `scripts.head` or `scripts.body`. + +--- + +- `seo` +- Added support for `meta` object. + +--- + +- `showNextButton` +- Moved to `navigation.nextButton`. + +--- + +- `showPrevButton` +- Moved to `navigation.previousButton`. + +--- + +- `stylesheets` +- Replaced by `links`. + See [links](https://www.redocly.com/docs/realm/config/links.md). + +--- + +- `toc` +- Moved to `markdown.toc`. + +{% /table %} + +#### Example configuration + +The following example shows a `siteConfig.yaml` file updated for the new product: + +{% tabs %} + {% tab label="Old project config"%} + ```yaml {% title="siteConfig.yaml" %} + seo: + title: Redocly Portal Example + siteUrl: https://portal-demo.redoc.ly + logo: + image: ./images/logo.png + altText: Portal logo + toc: + depth: 3 + disableLastModified: true + oasDefinitions: + museum-api: ./docs/openapi/museum.yaml + stylesheets: + - 'https://fonts.googleapis.com/css?family=Roboto:300,400,600,700' + scripts: + - ./static/intercom.js + nav: + - label: Training exercises + page: developer-portal/index.md + external: true + - label: External docs + icon: ./images/redocly-icon-white.png + href: 'https://redocly.com/docs/developer-portal/introduction/' + - search: true + footer: + copyrightText: Copyright © Redocly Portal Example + columns: + - group: Legal + items: + - label: Terms of Use + href: 'https://redocly.com/subscription-agreement/' + external: true + - label: Privacy Notice + href: 'https://redocly.com/privacy-policy/' + - group: Support + items: + - label: FAQ + page: faq.md + - label: Contact us + page: contact.mdx + ``` + {% /tab %} + {% tab label="New project config"%} + ```yaml {% title="redocly.yaml" %} + seo: + title: Redocly Portal Example + siteUrl: https://portal-demo.redoc.ly + apis: + museum-api: + root: ./docs/openapi/museum.yaml + logo: + image: ./images/logo.png + altText: Portal logo + markdown: + toc: + depth: 3 + lastUpdatedBlock: + hide: true + links: + - href: 'https://fonts.googleapis.com/css?family=Roboto:300,400,600,700' + scripts: + head: + - src: './static/intercom/js' + navbar: + items: + - label: Training exercises + page: developer-portal/index.md + external: true + - label: External docs + icon: ./images/redocly-icon-white.png + href: 'https://redocly.com/docs/developer-portal/introduction/' + - search: true + footer: + copyrightText: Copyright © Redocly Portal Example + items: + - group: Legal + items: + - label: Terms of Use + href: 'https://redocly.com/subscription-agreement/' + external: true + - label: Privacy Notice + href: 'https://redocly.com/privacy-policy/' + - group: Support + items: + - label: FAQ + page: faq.md + - label: Contact us + page: contact.mdx + ``` + {% /tab %} +{% /tabs %} + +### Migrate theme + +Realm contains major improvements and changes to project customization and building themes. +The new theming tools iterate on past capabilities, providing a better developer experience with more control. + +During migration, any theme customizations from your developer portal will need to be updated to work with Realm. + +#### Update project styles + +Realm adds support for [CSS variables](https://www.redocly.com/docs/realm/branding/css-variables), which are used to [customize the styles](https://www.redocly.com/docs/realm/branding/customize-styles.md) of your project and create a theme. + +During migration, follow the steps below to update your custom styling to work with Realm: + +1. Create a `@theme/styles.css` file with a root selector, as in the following example: + + ```css {% title="@theme/styles.css" %} + :root { + /* styles go here */ + } + ``` + +2. Open your `theme.ts` file. + +3. Recreate each styling rule using CSS variables. + See the [CSS variables reference](https://www.redocly.com/docs/realm/branding/css-variables) if you need help identifying them. + +The following example shows a set of style customizations from the developer portal updated to work with Realm: + +{% tabs %} + {% tab label="Old project styling"%} + ```javascript {% title="theme.ts" %} + export const theme = { + colors: { + primary: { + main: '#227a88', + }, + success: { + main: '#005e0a', + dark: '#00f71e', + }, + text: { + primary: '#424242', + secondary: '#4e566d', + }, + navbar: { + main: '#1A5761', + contrastText: 'white' + }, + }, + sidebar: { + backgroundColor: '#fafafa', + width: '260px', + }, + tocPanel: { + width: '240px', + }, + typography: { + fontSize: '14px', + lineHeight: '1.5em', + fontWeightRegular: '400', + fontWeightBold: '600', + fontFamily: '"Source Sans Pro", sans-serif', + headings: { + fontWeight: '600', + }, + heading2: { + fontSize: '18px', + fontWeight: '600', + color: '#2a2b2e', + }, + code: { + fontFamily: '"Source Code Pro", sans-serif', + color: '#e53935', + backgroundColor: '#ededf2', + }, + }, + codeBlock: { + backgroundColor: '#fbfbfc', + }, + }; + ``` + {% /tab %} + {% tab label="New project styling"%} + ```css {% title="@theme/styles.css" %} + :root { + --color-primary-main: #227a88; + + --admonition-success-bg-color: #00f71e; + + --text-color-primary: #424242; + --text-color-secondary: #4e566d; + + --navbar-bg-color: #1A5761; + --navbar-text-color: white; + + --sidebar-bg-color: #fafafa; + --sidebar-width: 260px; + + --toc-width: 240px; + + --font-size-base: 14px; + --line-height-base: 1.5em; + --font-weight-regular: 400; + --font-weight-bold: 600; + --font-family-base: 'Source Sans Pro', sans-serif; + --heading-font-weight: 600; + + --h2-font-size: 18px; + --h2-font-weight: 500; + --h2-text-color: #2a2b2e; + + --font-family-monospaced: 'Source Code Pro', sans-serif; + --inline-code-text-color: #e53935; + --inline-code-bg-color: #ededf2; + + --code-block-bg-color: + } + + :root.dark { + --color-primary-main: #227a88; + + --admonition-success-bg-color: #005e0a; + } + ``` + {% /tab %} +{% /tabs %} + +#### Update custom components + +Realm improves upon the concept of "component overrides" from the developer portal, but there are differences in implementation. +The core idea remains the same: replace the components used to build pages with custom React components that modify their behavior or appearance. + +During migration, update your custom components to reflect the following changes: + +- Custom components must be defined in the `@theme/components` folder, for example `@theme/components/Navbar/Navbar`. +- Realm is a complete rebuild. + The components in the core theme may have been removed or changed names. + +Realm adds support for an exciting new feature that allows you to [eject a component](https://www.redocly.com/docs/realm/customization/eject-components) used in the core theme. +That means you get a complete, working implementation of that component; ready to be customized. + +## Resources + +- **[Create React pages](https://www.redocly.com/docs/realm/customization/create-react-page.md)** - Build custom pages using React components for full control over layout, styling, and interactive functionality +- **[Navigation configuration](https://www.redocly.com/docs/realm/navigation/navigation.md)** - Configure navigation elements, menus, and page organization for optimal user experience in Realm projects +- **[Color mode customization](https://www.redocly.com/docs/realm/branding/customize-color-modes.md)** - Configure light and dark mode styling with custom color schemes and mode-specific CSS variables +- **[Front matter configuration](https://www.redocly.com/docs/realm/config/front-matter-config.md)** - Complete reference for page-level configuration options available through front matter settings diff --git a/docs-legacy/developer-portal/use-legacy-ui-components.md b/docs-legacy/developer-portal/use-legacy-ui-components.md new file mode 100644 index 00000000..2aed49c1 --- /dev/null +++ b/docs-legacy/developer-portal/use-legacy-ui-components.md @@ -0,0 +1,176 @@ +--- +excludeFromSearch: true +seo: + meta: + - name: robots + content: noindex +--- + +# Use legacy portal UI components + +The "UI components" from the legacy [Portal](https://redocly.com/docs-legacy/developer-portal) product are supported in Redocly's new suite of products. +However, they should only be used to help with migration. +We recommend replacing them as soon as possible. + +{% admonition type="warning" name="Warn" %} + The legacy UI components are deprecated and _will not receive future updates_. + Redocly's new products provide pre-built elements as [Markdoc tags](https://redocly.com/docs/learn-markdoc/tags/tag-library). +{% /admonition %} + +## Install package + +Install the @redocly/portal-legacy-ui package with your package manager: + +_npm_ + +```bash +npm install --save @redocly/portal-legacy-ui +``` + +_yarn_ + +```bash +yarn add @redocly/portal-legacy-ui +``` + +_pnpm_ + +```bash +pnpm add @redocly/portal-legacy-ui +``` + +## Import components + +At the top of a `.tsx` file, import the legacy components from the package: + +```javascript +import { ThinTile, TileHeader, TileText, WideTile, Box, Flex, Jumbotron } from '@redocly/portal-legacy-ui'; +``` + +You can use `.tsx` files in your project in two ways: +- [Creating a page with React](https://www.redocly.com/docs/realm/customization/create-react-page.md), for example: `example.page.tsx`. +- Creating a component to use in your theme or a [Markdoc tag](https://redocly.com/docs/learn-markdoc/tags/tag-library), for example `SomeComponent.tsx`. + +Remember that legacy ui components _will not_ receive future improvements. +Where possible, we recommend factoring them out. + +## Example - landing page + +The following example shows a landing page built with legacy components from the `@redocly/portal-legacy-ui` package: + +```javascript {% title="example.page.tsx" %} +import * as React from 'react'; +import styled from 'styled-components'; +import { ThinTile, TileHeader, TileText, WideTile, Box, Flex, Jumbotron } from '@redocly/portal-legacy-ui'; +import { H1, H2 } from '@redocly/theme'; + +export const frontmatter = { + header: { + hide: true, + }, + footer: { + hide: true, + } +}; + +export default function () { + return ( + + +

+ Example page header +

+ + with components from @redocly/portal-legacy-ui + + + + + + Key Features + + Cows + Spots, milk, and Mooooooooooo. + + + Frogs + Hops, long tongues,
and ribbit. + + + Flamingos + Pink, long neck,
stands on one leg. + + + + + + About Us + + Visit our delightful farm of cool creatures, where cows roam, frogs leap, and flamingos dance. + Our team is dedicated to crafting moo-velous solutions that make life as fun as a sunny day at the pond. + We're ready to tackle new challenges with cutting-edge lily pad technology. + + + + Address + + 1234 Creature Farm
+ Seattle, WA 12345
+ United States + + + + Contact Information + + Email: CowsFrogsFlamingos@example.com
+ Phone: (123) 456-7890
+ + + + + + ); +} + +const PageWrapper = styled.div` + padding: 10px; +`; + +const Description = styled.p` + font-size: 18px; + line-height: 1.6; + text-align: center; +` +export const About = styled(Box)` + background-color: #f8f9fa; + padding-top: 20px; + margin: 0; +` +export const Features = styled(Box)` + border: 1px dotted lightblue; + padding-top: 20px; +` +export const SectionHeader = styled(H2)` + width: 100%; + text-align: center; + margin-top: 0; +` + +export const HeroBanner = styled(Jumbotron)` + background-color: lightblue; + padding-bottom: 98px; +` + +export const HeroSubtext = styled.div` + font-size: 26px; + font-weight: 300; + text-align: center; + margin-top: 0; +`; +``` + +## Resources + +- **[Migrate from legacy Portal](./migrate-from-legacy-portal.md)** - Complete migration guide with step-by-step instructions for moving from the Portal product to modern Realm projects +- **[Learn Markdoc](https://redocly.com/docs/learn-markdoc/tags/tag-library)** - Comprehensive guide to Markdoc syntax and interactive components for enhanced technical writing and content creation +- **[Create React pages](https://www.redocly.com/docs/realm/customization/create-react-page.md)** - Build custom pages using React components for full control over layout, styling, and interactive functionality diff --git a/docs-legacy/workflows/migrate-api-refernce.md b/docs-legacy/workflows/migrate-api-refernce.md new file mode 100644 index 00000000..b508ee28 --- /dev/null +++ b/docs-legacy/workflows/migrate-api-refernce.md @@ -0,0 +1,291 @@ +# Migrate from Workflows + +This guide is for users of Redocly's earlier Workflows API Docs product. +The steps in this guide cover how to migrate from your existing setup to using Redoc. + +Redoc is our next-generation API reference documentation tool with code snippets, request/response examples, mock servers, and the Replay API explorer built into the page. +Publish Redoc projects to the Redocly Reunite platform (this version of Redoc is not licensed for use on other platforms; Enterprise+ customers may contact us to discuss other hosting arrangements). + +## Create a new project + +A [project](https://www.redocly.com/docs/realm/reunite/project/projects.md) is one website and everything that goes with it. +The project consists of files and folders; your project comes with a Redocly-hosted repository or you can connect your own Git repository. + +1. Sign up or log in to your Reunite account. + +2. Go to your [Reunite dashboard](https://app.cloud.redocly.com) and [create a new project](https://www.redocly.com/docs/realm/reunite/project/manage-projects.md#create-a-project). + +Every project is different, so there are multiple ways to add content to your project: + +- [Connect an existing Git repository](#connect-an-existing-git-repository) if you already use a repository source. +- [Upload an API description](#upload-an-api-description) to get started quickly. +- Use an [API description from an external URL](#add-an-api-from-an-external-url). +- If you prefer to use CI/CD to "push" content to a project, check the documentation for [pushing content from an external source](https://www.redocly.com/docs/realm/reunite/project/remote-content/push.md). + +### Connect an existing Git repository + +If you have your API descriptions stored in a Git repository, this repository becomes the source for your Redoc project. + +To make your existing Git repository the source for your Redoc project: +(../../reunite/project/connect-git/connect-git-provider.md) to get the existing content connected to the new project. + +2. Don't worry if the Workflows project content doesn't build successfully when you first connect it to Reunite. + The other sections in this guide cover the updates that may apply to your project. + +{% admonition type="info" name="Use remote content for multiple repositories"%} +If you have API descriptions in multiple repositories, the [remote content](https://www.redocly.com/docs/realm/reunite/project/remote-content/remote-content.md) feature supports connecting another repository (or more than one) as a source for the project. +{% /admonition %} + +### Upload an API description + +Upload your API description directly in the Editor for your project. +If you were using configuration in your Workflows project, add it to a file named `redocly.yaml`, and follow the steps in the section about [updating configuration options](#update-existing-configuration-options) later in this guide. + +### Add an API from an external URL + +If your API files are in a separate project than your Redocly setup, add them using the [remote content](https://www.redocly.com/docs/realm/reunite/project/remote-content/remote-content.md) feature. + +To add content using the remote content feature: + +1. Go to the Reunite editor in your new project. + +2. Click the plus sign icon (Add content) and select **New remote**. + +3. Select **Add URL link**, and enter the following required fields: + + - the URL of the API description + - the file name to use in Reunite + - how often to check for updates + - where in the project to mount the file, such as `apis/my-api-name.yaml` + +The API description is added to your project and you can see it in the preview. + +## Multiple APIs + +Redoc supports multiple API references in a single project. +Add each API description to your project, either directly or using [remote content](#add-an-api-from-an-external-url). + +Add a `sidebars.yaml` file to the root of your project, and add each API to it as shown in the following example: + +```yaml {% title="sidebars.yaml" %} +- group: Orders + page: apis/orders/openapi.yaml +- group: Accounts + page: apis/accounts/openapi.yaml +``` + +You can customize the order and display labels of the APIs, or group in another structure to suit your needs. +Visit the [sidebars documentation](https://www.redocly.com/docs/realm/navigation/sidebars.md) for more information and examples. + +## Multiple API versions + +If you were using multiple versions of a single API, you can do the same thing with updated Redoc, but the structure looks a little different. + +To create a structure for versioned APIs: + +1. Create one folder per version, starting with an `@` character. + For example, if you have two versions of your API, version 10 and version 12, you might create a folder structure like this: + + - `apis/@v10/` + - `apis/@v12/` + +1. Add the OpenAPI descriptions to the folders. + +1. In the project (or preview), use the dropdown to switch between versions; it retains the user's position in the API reference documentation for any entries which exist in both versions. + +2. (Optional) For additional control, [configure a `versions.yaml` file](https://www.redocly.com/docs/realm/content/versions.md) to specify which versions should be displayed or not, and which is the default version. + +## Update existing configuration options + +If you had an existing `redocly.yaml`, there may be settings that need updating. +Feedback about outdated or unknown configuration options is available either [using Redocly CLI on your computer](#check-configuration-locally) or [using Reunite](#check-configuration-with-reunite). + +### Check configuration with Reunite + +Open the `redocly.yaml` file in the editor. +The editor will indicate any configuration that isn't supported in the newer products. +Check the list of [configuration updates](#update-configuration-settings) for advice on changing some of the most common settings as part of your migration project. + +### Check configuration locally + +Redocly CLI can help identify those changes, and verify that the config file is correct. + +Start by checking the config with Redocly CLI using the following command: + +```bash +redocly check-config +``` + +If there are settings that are outdated or unrecognized, the output displays warnings or errors. + +### Update configuration settings + +The following table shows how to update some commonly used configuration options to work with the new product: + +{% table %} + +- Previous configuration +- Replacement values + +--- + +- `referenceDocs` +- This section is replaced by the `openapi` configuration setting. + For example: + + ```yaml + openapi: + showExtensions: true + ``` + + Check the [openapi configuration documentation](https://www.redocly.com/docs/realm/config/openapi) for all the options for configuring reference documentation. + +--- + +- `htmlTemplate` +- Instead of supplying a template, use the configuration options for the navbar, sidebar, and footer sections. + The [navigation documentation](https://www.redocly.com/docs/realm/navigation/navigation.md) is a good starting point to find out more about each element. + +--- + +- `apiDefinitions` +- Replace with `apis` and one named entry for each API in your project. + Check the [`apis` configuration reference](https://redocly.com/docs/cli/configuration/reference/apis) for more information and examples. + +--- + +- `lint` +- The `lint` entry is no longer needed. + Instead, use the keys such as `extends` and `rules` at the top level of the `redocly.yaml` configuration file. + +--- + +- `assert/*` +- The [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) syntax changed. + Use `rule/` instead of `assert/` and check the configurable rules documentation for other changes. + +--- + +- `pagination` +- Not supported. + This version of Redoc has a modern style of pagination, operations are divided into sections by tags. + +--- + +- `hideTryItPanel` or the older `hideConsole` +- Replaced by `hideReplay` as the "Try It" functionality is provided by [Replay](https://redocly.com/docs/end-user/test-apis-cli). + +--- + +- `hideDownloadButton` +- Now named `hideDownloadButtons` since we support multiple downloads. + Visit the [documentation for hiding download buttons](https://www.redocly.com/docs/realm/config/openapi/hide-download-buttons.md) for more information. + +--- + +- `requiredPropsFirst` +- Renamed to `sortRequiredPropsFirst`. + View the [detailed documentation for sortRequiredPropsFirst](https://www.redocly.com/docs/realm/config/openapi/sort-required-props-first.md) for more information. + + For more sorting options, try the [sorting plugin](https://github.com/Redocly/redocly-cli-cookbook/tree/main/custom-plugins/sorting) from the Redocly CLI cookbook. + The plugin also includes a `property-sort` rule to check property ordering. + +--- + +- `sortPropsAlphabetically` +- Removed, but can be replaced using a custom decorator such as the `properties-alphabetical` decorator in the [sorting plugin](https://github.com/Redocly/redocly-cli-cookbook/tree/main/custom-plugins/sorting) from the Redocly CLI cookbook. + The plugin also includes a `property-sort` rule to check property ordering. + +--- + +- `sortEnumValuesAlphabetically` +- Removed, use a custom decorator instead. + Try the `enums-alphabetical` decorator in the [sorting plugin](https://github.com/Redocly/redocly-cli-cookbook/tree/main/custom-plugins/sorting) from the Redocly CLI cookbook. + +--- + +- `sortTagsAlphabetically` + Try the `tags-alphabetical` decorator in the [sorting plugin](https://github.com/Redocly/redocly-cli-cookbook/tree/main/custom-plugins/sorting) from the Redocly CLI cookbook. + + +--- + +- `generatedPayloadSamplesMaxDepth` +- Renamed to `generatedSamplesMaxDepth`. + The [documentation for generatedSamplesMaxDepth](https://www.redocly.com/docs/realm/config/openapi/generated-samples-max-depth.md) includes more information and examples. + +--- + +- `jsonSampleExpandLevel` +- Renamed to `jsonSamplesExpandLevel`. + The [documentation for jsonSamplesExpandLevel](https://www.redocly.com/docs/realm/config/openapi/json-samples-expand-level.md) includes more information and examples. + +--- + +- `schemaExpansionLevel` +- Renamed to `schemasExpansionLevel`. + The [documentation for schemasExpansionLevel](https://www.redocly.com/docs/realm/config/openapi/schemas-expansion-level.md) includes more information and examples. + +{% /table %} + +> If you spot another configuration setting that should be included in this guide, leave some feedback at the bottom of the page to let us know. + +## Style the output + +The styling mechanism had a big upgrade in the new products, and is now based on CSS variables for a more customizable and flexible experience. +Set colors, fonts, and styles by configuring your own theme. + +To apply custom styles to your project: + +1. Create a directory called `@theme/` at the top level of your project. +2. Add a `styles.css` file inside the new directory. +3. To get you started with an example, paste the following example content: + + ```css {% title="@theme/styles.css" %} + :root { + --heading-text-color: var(--color-purple-7); + --text-color-secondary: #22242b; + --sidebar-bg-color: ivory; + --panel-border: 3px solid teal; + } + + :root.dark { + --sidebar-bg-color: midnightblue; + --text-color-secondary: #ffffdf; + } + + ``` + + This snippet changes a few colors in both light and dark modes, and the preview automatically updates to reflect the changes. + +4. Edit the `@theme/styles.css` file to reflect your own branding and preferences. + Using "Inspect" in your browser developer tools shows the CSS class names that you can change. + The documentation includes [branding and customization guides](https://www.redocly.com/docs/realm/branding) to help you get started, and a full [CSS variables dictionary](https://www.redocly.com/docs/realm/branding/css-variables) for your reference. + +## Local development platform + +Using a local development platform requires that your Reunite project exists in your own Git provider. +Our tools are based on [NodeJS](https://nodejs.org/en), so you will also need version 22.12.0 or later (alternatively -- v20.19.0 or later) and [npm](https://docs.npmjs.com/cli/v10/commands/npm) installed. + +To run your project locally: + +1. Install [Redocly CLI](https://redocly.com/docs/cli/installation). + +1. Before making any changes, try the out-of-the-box Redoc experience by running the following command: + + ```bash + redocly preview + ``` + + The `preview` command starts a local server, visit the URL shown (usually ``) to get a first glimpse of your API rendered with the newer Redoc tools. + +1. Use the sections throughout the guide to structure your repository to suit your needs, update the configuration, and adjust the styles as needed. + +## Next steps + +There are many more aspects to Redoc that you might like to explore. +Here are some suggestions for where to go next: + +- View the list of [supported OpenAPI extensions](https://www.redocly.com/docs/realm/content/api-docs/openapi-extensions). +- Check the [configuration options for OpenAPI documentation](https://www.redocly.com/docs/realm/config/openapi), there are changes and additions in comparison to our older products. +- Learn how to [set a custom domain](https://www.redocly.com/docs/realm/reunite/project/custom-domain.md) for your project. From b67106be8c09fb0b81145dbfd7b8b8540a0c0eda Mon Sep 17 00:00:00 2001 From: Roman Sainchuk Date: Tue, 7 Apr 2026 19:47:48 +0300 Subject: [PATCH 3/7] chore(other): trigger ai-review From 6fbb5b22e330daf3f1977eb0b206a38a11c8d2f3 Mon Sep 17 00:00:00 2001 From: JLekawa Date: Thu, 9 Apr 2026 11:54:43 +0200 Subject: [PATCH 4/7] docs(other): fix links and redirects --- docs-legacy/developer-portal/migrate-from-legacy-portal.md | 4 ++-- redirects.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs-legacy/developer-portal/migrate-from-legacy-portal.md b/docs-legacy/developer-portal/migrate-from-legacy-portal.md index 1104f2fe..8385ae6d 100644 --- a/docs-legacy/developer-portal/migrate-from-legacy-portal.md +++ b/docs-legacy/developer-portal/migrate-from-legacy-portal.md @@ -193,8 +193,8 @@ The following example shows the old and new syntax for using remote API descript In this example, both API definitions are set up as remote content sources and the `redocly.yaml` file uses relative file paths. - - The art-museum uses [remote content from GitHub](../../reunite/project/remote-content/from-github.md). - - The flight-museum uses [remote content from a URL](../../reunite/project/remote-content/url.md). + - The art-museum uses [remote content from GitHub](https://www.redocly.com/docs/realm/reunite/project/remote-content/from-github.md). + - The flight-museum uses [remote content from a URL](https://www.redocly.com/docs/realm/reunite/project/remote-content/url.md). ```yaml {% title="redocly.yaml" %} apis: diff --git a/redirects.yaml b/redirects.yaml index d9b367f7..98eb4332 100644 --- a/redirects.yaml +++ b/redirects.yaml @@ -772,7 +772,7 @@ # Redirects after moving migration files '/docs/realm/get-started/migrate-from-legacy-portal': - to: '/docs/realm/get-started/migrate/migrate-from-legacy-portal' + to: '/docs-legacy/developer-portal/migrate-from-legacy-portal' '/docs/realm/get-started/migrate-api-reference': - to: '/docs/realm/get-started/migrate/migrate-api-reference' + to: '/docs-legacy/workflows/migrate-api-reference' From be3f83185a3958fd1fce6cbc0b1e21a9628559a9 Mon Sep 17 00:00:00 2001 From: JLekawa Date: Thu, 9 Apr 2026 12:41:40 +0200 Subject: [PATCH 5/7] docs(other): fix links in banner and product timeline page --- docs-legacy/_snippets/banner-legacy-developer-portal.md | 4 ++-- pages/product-timelines/product-timelines.md | 8 ++++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs-legacy/_snippets/banner-legacy-developer-portal.md b/docs-legacy/_snippets/banner-legacy-developer-portal.md index f14d885c..f644ddaa 100644 --- a/docs-legacy/_snippets/banner-legacy-developer-portal.md +++ b/docs-legacy/_snippets/banner-legacy-developer-portal.md @@ -1,5 +1,5 @@ {% admonition type="danger" name="Deprecated docs" %} -The developer portal beta is [approaching end of life](/product-timelines). +The developer portal beta is [approaching end of life](../../pages/product-timelines/product-timelines.md). -Use Realm and Reunite instead. Read the [migration guide](../../docs/realm/get-started/migrate-from-legacy-portal.md). +Use Realm and Reunite instead. Read the [migration guide](../developer-portal/migrate-from-legacy-portal.md). {% /admonition %} diff --git a/pages/product-timelines/product-timelines.md b/pages/product-timelines/product-timelines.md index 94dce2b4..0d7485ac 100644 --- a/pages/product-timelines/product-timelines.md +++ b/pages/product-timelines/product-timelines.md @@ -19,8 +19,12 @@ For users of the beta version of the Developer Portal, consider Revel with Redoc ### How to migrate We’ve prepared detailed migration guides for our two major products. These guides are technical and designed to help you transition smoothly: -- [API docs Migration Guide](../../docs/realm/get-started/index.md) -- [Developer Portal (Gatsby Portal) Migration Guide](../../docs/realm/get-started/index.md) +- [API docs Migration Guide](../../docs-legacy/workflows/migrate-api-refernce.md) +- [Developer Portal (Gatsby Portal) Migration Guide](../../docs-legacy/developer-portal/migrate-from-legacy-portal.md) + +We also have two guides to help you get started with our new products: +- [Start working with Reunite](../../docs/realm/get-started/start-reunite-editor.md) +- [Start with local development](../../docs/realm/get-started/start-local-dev.md) ### Future products From 860cf6e67c6c5a0b25da6dd6d720c3d8d168d55a Mon Sep 17 00:00:00 2001 From: JLekawa Date: Thu, 9 Apr 2026 12:47:46 +0200 Subject: [PATCH 6/7] docs(other): fix broken link to migration --- pages/billing/signup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/billing/signup.md b/pages/billing/signup.md index c3173799..6f03e30d 100644 --- a/pages/billing/signup.md +++ b/pages/billing/signup.md @@ -105,7 +105,7 @@ Redocly Workflows is being sunset on February 28, 2026. If you're currently usin 1. **[Sign up](https://auth.cloud.redocly.com/registration)** using the same email address you used in Workflows. This will help ensure a smooth transition. 2. **Create your organization** - This will automatically start your free 30-day trial. -3. **Complete the migration** - Follow our [technical migration guides](/docs/realm/get-started/migrate-api-reference) to migrate your content and configuration from Workflows to Reunite. +3. **Complete the migration** - Follow our [technical migration guides](/docs-legacy/workflows/migrate-api-reference) to migrate your content and configuration from Workflows to Reunite. 4. **Subscribe and set up billing** - Billing for Reunite is separate from Workflows, so you'll need to set up a new subscription. 5. **Cancel your Workflows subscription** - Once your migration is complete and verified, you can cancel your Workflows subscription. From c71ea3e5cf654841372911614f9b977329cd8121 Mon Sep 17 00:00:00 2001 From: JLekawa Date: Thu, 9 Apr 2026 13:00:46 +0200 Subject: [PATCH 7/7] docs(other): apply suggestions from review --- docs-legacy/_snippets/banner-legacy-developer-portal.md | 4 ++-- .../{migrate-api-refernce.md => migrate-api-reference.md} | 4 ++-- pages/product-timelines/product-timelines.md | 2 +- redirects.yaml | 2 ++ 4 files changed, 7 insertions(+), 5 deletions(-) rename docs-legacy/workflows/{migrate-api-refernce.md => migrate-api-reference.md} (98%) diff --git a/docs-legacy/_snippets/banner-legacy-developer-portal.md b/docs-legacy/_snippets/banner-legacy-developer-portal.md index f644ddaa..5b94c4df 100644 --- a/docs-legacy/_snippets/banner-legacy-developer-portal.md +++ b/docs-legacy/_snippets/banner-legacy-developer-portal.md @@ -1,5 +1,5 @@ {% admonition type="danger" name="Deprecated docs" %} -The developer portal beta is [approaching end of life](../../pages/product-timelines/product-timelines.md). +The developer portal beta is [approaching end of life](/pages/product-timelines/product-timelines.md). -Use Realm and Reunite instead. Read the [migration guide](../developer-portal/migrate-from-legacy-portal.md). +Use Realm and Reunite instead. Read the [migration guide](/docs-legacy/developer-portal/migrate-from-legacy-portal.md). {% /admonition %} diff --git a/docs-legacy/workflows/migrate-api-refernce.md b/docs-legacy/workflows/migrate-api-reference.md similarity index 98% rename from docs-legacy/workflows/migrate-api-refernce.md rename to docs-legacy/workflows/migrate-api-reference.md index b508ee28..32e35aac 100644 --- a/docs-legacy/workflows/migrate-api-refernce.md +++ b/docs-legacy/workflows/migrate-api-reference.md @@ -27,9 +27,9 @@ Every project is different, so there are multiple ways to add content to your pr If you have your API descriptions stored in a Git repository, this repository becomes the source for your Redoc project. To make your existing Git repository the source for your Redoc project: -(../../reunite/project/connect-git/connect-git-provider.md) to get the existing content connected to the new project. +(https://www.redocly.com/docs/realm/reunite/project/connect-git/connect-git-provider.md) to get the existing content connected to the new project. -2. Don't worry if the Workflows project content doesn't build successfully when you first connect it to Reunite. +1. Don't worry if the Workflows project content doesn't build successfully when you first connect it to Reunite. The other sections in this guide cover the updates that may apply to your project. {% admonition type="info" name="Use remote content for multiple repositories"%} diff --git a/pages/product-timelines/product-timelines.md b/pages/product-timelines/product-timelines.md index 0d7485ac..2bb48aba 100644 --- a/pages/product-timelines/product-timelines.md +++ b/pages/product-timelines/product-timelines.md @@ -19,7 +19,7 @@ For users of the beta version of the Developer Portal, consider Revel with Redoc ### How to migrate We’ve prepared detailed migration guides for our two major products. These guides are technical and designed to help you transition smoothly: -- [API docs Migration Guide](../../docs-legacy/workflows/migrate-api-refernce.md) +- [API docs Migration Guide](../../docs-legacy/workflows/migrate-api-reference.md) - [Developer Portal (Gatsby Portal) Migration Guide](../../docs-legacy/developer-portal/migrate-from-legacy-portal.md) We also have two guides to help you get started with our new products: diff --git a/redirects.yaml b/redirects.yaml index 98eb4332..011b53d5 100644 --- a/redirects.yaml +++ b/redirects.yaml @@ -775,4 +775,6 @@ to: '/docs-legacy/developer-portal/migrate-from-legacy-portal' '/docs/realm/get-started/migrate-api-reference': to: '/docs-legacy/workflows/migrate-api-reference' +'docs/realm/get-started/use-legacy-ui-components': + to: '/docs-legacy/developer-portal/use-legacy-ui-components'