Migrate from Docs 1.0

TL;DR

Migrate your scalar.config.json with: npx @scalar/cli project upgrade

New Features in Docs 2.0#

MDX support with custom components
[relative Markdown paths](https://scalar.com/products/docs/your-other-file.md)
Per-operation page rendering for API references (huge performance boost for large OpenAPI documents)
Configurable navigation structures: nested, grouped, or flattened
Full <head> customization (meta tags, scripts, stylesheets)
Local file imports for CSS, scripts, and static assets
Local OpenAPI file references with $ref resolution
Subpath deployment with unified cross-project search
"Copy as Markdown"
… and so much more, it's crazy.

How do I know whether I use Docs 1.0?#

If you created a project before February 2026, you probably use Docs 1.0:

// scalar.config.json (Docs 1.0)
{
  "$schema": "https://cdn.scalar.com/schema/scalar-config.json",
  "siteConfig": {
    // …
  },
  "guides": [
    // …
  ],
  "references": [
    // …
  ],
}

For Docs 2.0 we still use the scalar.config.json, but the structure changed a bit:

// scalar.config.json (Docs 2.0)
{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    // …
  },
  "siteConfig": {
    // …
  },
  "navigation": {
    "routes": {
      // …
    }
  }
}

Do you have to switch to 2.0?#

Actually, under the hood, you’re using Docs Version 2 already.

If you want to actually use new features and upgrade your configuration file use the CLI to upgrade:

npx @scalar/cli project upgrade

Check how your documentation looks with:

npx @scalar/cli project preview

If it's good, commit and push the upgraded configuration to your repository – done!

Updated Sep 24, 2026