How to migrate from ReadMe to Scalar

You have two routes out, and both give you Markdown files with YAML frontmatter.

Bi-directional sync. ReadMe syncs with GitHub, GitLab, or Bitbucket. Every content type syncs, including guides, API reference pages, custom pages, recipes, and changelogs. Page order is kept in _order.yaml files, and each Git branch maps to a ReadMe version with exactly the same name. ReadMe requires the target repository to be empty when you connect it. If you already sync, your content is in Git and you can skip ahead.

The rdme CLI. Version 10 of rdme is built for ReadMe Refactored projects. Its docs export command writes your guides to a folder:

npx rdme docs export ./docs --key "$README_API_KEY" --branch stable

Repeat with --branch for each version you still publish. rdme also has a reference command for exporting API reference pages, which matters only if you wrote long-form content on those pages; the reference itself will come from your OpenAPI document.

Your OpenAPI document. If you upload it with rdme openapi upload, the source file is already in your repository. Before you move, run ReadMe's own inspector to see which ReadMe-specific features the document uses:

npx rdme openapi inspect openapi.yaml

The inspect command analyses ReadMe feature usage, which gives you a checklist for step 3.

Scalar keys every route by its URL. If you keep ReadMe's /docs prefix as a group, your guide URLs can stay the same. Use the slugs from your exported files and the order from _order.yaml:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    "title": "Acme Developer Hub"
  },
  "navigation": {
    "tabs": [
      { "title": "Guides", "to": "/docs/getting-started" },
      { "title": "API Reference", "to": "/reference" },
      { "title": "Changelog", "to": "/changelog" }
    ],
    "routes": {
      "/docs": {
        "type": "group",
        "title": "Guides",
        "mode": "flat",
        "children": {
          "/getting-started": {
            "type": "page",
            "title": "Getting started",
            "filepath": "docs/getting-started.md"
          },
          "/authentication": {
            "type": "page",
            "title": "Authentication",
            "filepath": "docs/authentication.mdx"
          }
        }
      },
      "/reference": {
        "type": "openapi",
        "title": "API Reference",
        "filepath": "openapi.yaml"
      },
      "/changelog": {
        "type": "group",
        "title": "Changelog",
        "mode": "folder",
        "children": {
          "/2026-09-launch": {
            "type": "page",
            "title": "September launch",
            "filepath": "changelog/2026-09-launch.md"
          }
        }
      }
    }
  },
  "siteConfig": {
    "subdomain": "acme",
    "rss": {
      "path": "/changelog",
      "title": "Acme Changelog",
      "entries": "pages"
    }
  }
}

If you publish several ReadMe versions, use versions instead of navigation, with a default version for the one ReadMe serves when no version is in the URL. Check the file with npx @scalar/cli project check-config.

Your OpenAPI document renders in Scalar as it is. Code samples you wrote under x-readme.code-samples show up without edits, in the "Code Examples" group of the language picker. The rest of ReadMe's extensions are ignored rather than rejected, so nothing breaks, but here is how to get the same behaviour:

Configuration goes on the route:

"/reference": {
  "type": "openapi",
  "title": "API Reference",
  "filepath": "openapi.yaml",
  "config": {
    "defaultHttpClient": { "targetKey": "node", "clientKey": "undici" },
    "authentication": {
      "preferredSecurityScheme": "apiKey"
    }
  }
}

ReadMe pages are MDX. Scalar Docs supports MDX too, but only in files with an .mdx extension, so rename any exported file that uses components.

The ReadMe column comes from its built-in components and features documentation.

Recipes. ReadMe recipes are step-by-step code walkthroughs that open as modals from guides or the reference. Scalar has no modal walkthrough. The closest equivalent is a regular page built from <Steps>, with a code block in each step, linked from the relevant guide.

Changelog. Each exported changelog post becomes a page under /changelog. Add a date to its frontmatter and set "entries": "pages" on the feed, as in step 2, and Scalar publishes /changelog/rss.xml with one item per post:

---
date: 2026-09-15
---

# September launch

New endpoints for webhooks and a longer rate limit window.

ReadMe's personalized docs log developers in through ReadMe, your own login via JWT, or SSO on Enterprise, then show each developer their own API keys and server variables, and let you use user data as variables in your pages.

Scalar covers part of this, and it is worth being exact about which part:

• Restricting who can read the docs is covered. Private docs with access groups are on Pro and above, and you can brand the sign-in page with a custom login portal.
• Prefilling credentials in the API client is covered with the authentication configuration, but the values are set per site, not per logged-in developer.
• Per-developer keys and variables in page content are not covered. If your onboarding depends on showing each developer their own key, plan to handle that in your dashboard and link to it from the docs.

ReadMe URLs follow /{version}/{type}/{slug}, where the version segment is optional and the type is docs, reference, changelog, or page (docs). If you kept /docs and /changelog as group paths in step 2, most guide URLs survive unchanged. Reference pages will not, because Scalar generates its own operation URLs, and neither will custom pages or versioned URLs.

Existing ReadMe redirects live under Settings > Errors & Redirects, one oldurl -> newurl rule per line, with JavaScript regular expressions allowed (docs). Copy those across, then add rules for everything that moved, under siteConfig.routing.redirects:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "siteConfig": {
    "routing": {
      "redirects": [
        { "from": "/page/support", "to": "/docs/support" },
        { "from": "/reference/get-user", "to": "/reference" },
        { "from": "/v1.0/:pathMatch(.*)*", "to": "/docs/getting-started" }
      ]
    }
  }
}

Scalar's documented wildcard and regex examples send every match to one destination, so list individual rules for any page that should land somewhere specific.

Preview with npx @scalar/cli project preview, connect Git Sync so merges publish, and review the site on its apidocumentation.com subdomain. Move the custom domain last. ReadMe has you point a CNAME at a readmessl.com target (docs); for Scalar, add customDomain to siteConfig, publish, then change the CNAME to dns.scalar.com with any proxy turned off. Custom domains are on Scalar Pro and above. See Domains.