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.

Sign up or log in to your Reunite account.
(Optional) Add an identity provider and configure SSO.
Go to your Reunite dashboard and create a new project.
Go to Settings --> Git hosting and connect your existing repository.
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.

Create a new branch in your remote repository to contain migration changes; for example, your new branch name could be portal-upgrade.
On the new branch, create a migration-test.md file and open a pull request against your repository's main branch.
In Reunite, go to your project's Settings --> Git hosting and update the connection to use the new migration branch, portal-upgrade.
Check the Reunite Editor to verify your new file is present.
(Optional) Depending on your timeline, you may consider locking your repository 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.

From your migration branch (portal-upgrade), create a new branch to work from; for example, your new branch could be named migrate-sidebar.
Use this guide to migrate each part of your project. In this example, that's the Update sidebar section.
Run the local Realm preview to see the changes while you work.
Open a pull request in your repository to merge the migrate-sidebar branch into portal-upgrade.
Review the code and the branch preview build.
(Optional) Explore the other tools in Reunite, such as visual review.
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

Go to your Git provider and suspend the Redocly Workflows app.
In Reunite, go to the project's Settings --> Git hosting and update the connection to use the main, or production, branch of your repository.
Merge your migration branch, portal-upgrade, into your production branch, main.
Review the production deployment of the site to ensure it's ready for release.
In Reunite, set a custom domain for your project.
Update your CNAME record to point to ssl.cloud.redocly.com. This change can take up to 8 hours to propagate depending on your provider.
(Optional) Delete 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 that can automate many of the syntax changes required during migration. This script can save you time and reduce the likelihood of manual errors.

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.

Use migration script

Open your project to the migration branch (i.e. portal-upgrade).
Remove the node_modules folder.
Run the following command to install and execute the script: npm exec github:redocly-demo/migrate-portal.
Navigate the script prompts. The script analyzes your project files and automatically make the necessary syntax changes.
Review the _MIGRATION.md file and make additional changes as needed.
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:

Remove "developer-portal" from your npm modules: npm uninstall --save @redocly/developer-portal
Add the Realm library: npm install --save @redocly/realm
Clear your project's cache: rm -rf node_modules && rm -rf package-lock.json && npm install

In your package.json file, add a script that runs the Redocly CLI preview command:

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. 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 connections for any externally-maintained API descriptions.

The following example shows the old and new syntax for using remote API descriptions:

In this example, the siteConfig.yaml file uses direct pointers to the remote API definitions.

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

Centralized API reference configuration

In Realm, configuring the default API reference settings remains the same (using theme.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:

art/art-museum.page.yaml

type: reference-docs
definitionId: art-museum
settings:
  hideDownloadButtons: true
  codeSamples:
    skipOptionalParameters: true
    languages:
      - lang: 'curl'
        label: 'cURL'

flight/flight-museum.page.yaml

type: reference-docs
definitionId: flight-museum
settings:
  hideDownloadButtons: false
  hideSchemaTitles: true
  codeSamples:
    skipOptionalParameters: false
    languages:
      - lang: 'JavaScript'
        label: 'JS'

When multiple APIs are configured, Realm and Reef users can also use the API catalog feature.

New API catalog format

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 API catalog feature is already built into the product and is enabled through configuration.

Use the following guide to enable the API catalog during your migration: Add a catalog.

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. 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 if you'd like to update them all at once.

The following example shows the old and new admonition syntax:

:::info Optional title

Just FYI

:::

Change reusable snippets

Realm adds a Markdoc tag for partials, which is a big upgrade for working with reusable content. The developer portal's approach to reusable content, which used Markdown snippets in an HTML <embed> tag, is no longer supported.

During migration, replace any embedded Markdown snippets with the new partials tag, as in the following example:

# Example page

Follow the steps below before starting this tutorial:

<embed src="/shared/tutorial/_common-setup-snippet.md" />

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:

```python example.py
def hello_world():
  print("Hello, World!")

hello_world()
```

Change tabbed code samples

Realm adds a Markdoc tag for 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:

  ```javascript
  javascript;
  ```

  ```python
  python
  ```

  ```java title
  example text
  ```

  ```custom tab name
  example text
  ```

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:

---
redirectFrom:
  - /docs/api-reference/on-premise/license-key/
  - /another-example-page/
  - /2020/12/example-blog-post/
---

# Example H1 under front matter

Update MDX files

MDX files do not render in Realm because support for MDX was removed in favor of Markdoc, 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. 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:

Change the filetype from .mdx to .md.

Remove the JSX syntax from the file. Alternatively, you can comment it out and use it to create a tag later.

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.

<!-- <ProductGallery /> -->

(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.

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 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:

<OpenApiTryIt
  definitionId="museumApi"
  operationId="listSpecialEvents"
  parameters={{
    query: {
      limit: 10
    },
    header: {
      exampleKey: "exampleValue"
    }
  }}
/>

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 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:

Copy the JSX from the migrated file.
Add it as a custom component. For example, @theme/markdoc/components/YourComponent.tsx.
Export the component from @theme/markdoc/components.tsx.
Define the Markdoc tag schema, @theme/markdoc/components/YourComponent-Schema.ts.
Export the tag from @theme/markdoc/schema.tsx.

Now authors can use the Markdoc tag to render the same element from the migrated JSX.

This section explains the process for migrating custom elements. For more detailed guidance on creating tags, see See Build a Markdoc tag.

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.

Settings for the navigation bar have changed.

During migration, update your navbar configuration to reflect the following changes:

The nav property was renamed and moved to theme.navbar.
Navbar entries must be listed in an items property.
The search property was removed from navbar config and added as a search option.
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:

Settings for the footer have some small but structural changes.

During migration, update your footer configuration to reflect the following changes:

The footer property was moved to theme.footer.
The columns property was renamed to items.

The following example the same footer settings using the old and new syntax:

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

New settings and features were added to the sidebar.

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:

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

After your sidebar config works with Realm, explore the following new sidebar features:

Build sidebars using configuration from multiple files using fragments.
Use set sidebar to show the sidebar on a page without listing it on sidebars.yaml.
Control the visibility of sidebar entries with RBAC.

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:

Rename the siteConfig.yaml file to redocly.yaml.
Update your configuration to reflect the changes in the table below.
Test the configuration in Realm and work through any errors.
After migration, explore and add new configuration options.

The following table summarizes the changes to the configuration options for the developer portal:

Legacy config option	Change in Realm
`analytics`	Moved to `theme.analytics`.
`copyCodeSnippet`	Replaced by `theme.codeSnippet`. New features added, see codeSnippet.
`disableLastModified`	Replaced by `theme.markdown.lastUpdatedBlock`. New features added, see last updated object.
`editPage`	Moved to `theme.markdown.editPage`.
`footer`	Moved to `theme.footer`. New syntax and features, see footer.
`logo`	Moved to `theme.logo`. Now supports light mode / dark mode versions.
`nav`	Replaced by `theme.navbar`. New syntax and features, see navbar options or update navbar.
`oasDefinitions`	Replaced by `apis`. Syntax changes, see 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 `theme.links`. See links.
`toc`	Moved to `theme.markdown.toc`.

Example configuration

The following example shows a siteConfig.yaml file updated for the new product:

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

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, which are used to customize the styles of your project and create a theme.

During migration, follow the steps below to update your custom styling to work with Realm:

Create a @theme/styles.css file with a root selector, as in the following example:
@theme/styles.css
```
:root {
  /* styles go here */
}
```
Open your theme.ts file.
Recreate each styling rule using CSS variables. See CSS variables in Realm if you need help identifying them.

The following example shows a set of style customizations from the developer portal updated to work with Realm:

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',
  },
};

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 used in the core theme. That means you get a complete, working implementation of that component; ready to be customized.

Resources

Create a React page for full control over all page elements.
Learn more about the navigation elements in Realm.
Configure light and dark mode in your project using color mode.
See which front matter options are available for page-level configuration.

Migrate from legacy portal

Migration overview

Connect services to Reunite

Prepare for migration

Execute migration

Publish migrated project

Migration helper script

Use migration script

Limitations of script

Migrate portal project

Run local Realm preview

Migrate content

Update API reference

API descriptions as remote content

Centralized API reference configuration

New API catalog format

Update Markdown files

Change admonition syntax

Change reusable snippets

Change code fence titles

Change tabbed code samples

Change page-level redirects

Update MDX files

Change OpenApiTryIt component

Create Markdoc tags from JSX

Migrate navigation

Update navbar

Update footer

Update sidebar

Migrate configuration

Example configuration

Migrate theme

Update project styles

Update custom components

Resources

Was this helpful?