scalar-docs

Scalar Docs Configuration Skill — scalar.config.json

Reference for writing and updating scalar.config.json, the central configuration file for Scalar Docs. Use this when creating, editing, or validating Docs configuration for any project.

Overview

• File: scalar.config.json (or scalar.config.json5)
• Location: Repository root by default; path can be overridden in Scalar Dashboard
• Schema: https://registry.scalar.com/@scalar/schemas/config — enables autocomplete in VS Code/Cursor when json.schemaDownload.enable is true
• Version: Use "scalar": "2.0.0" for the latest format

Quick Start

Create a minimal config:

npx @scalar/cli project init

Minimal structure:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    "title": "My Documentation",
    "description": "The best documentation you've read today"
  },
  "navigation": {
    "routes": {
      "/": {
        "title": "Introduction",
        "type": "page",
        "filepath": "docs/introduction.md"
      }
    }
  }
}

Validate config: npx @scalar/cli project check-config

---

Root Properties

---

info

Project metadata displayed across the site:

{
  "info": {
    "title": "My Documentation",
    "description": "Comprehensive guides for our API"
  }
}

---

navigation

All navigation is in navigation.routes. Each route key is the URL path; the value is a config object.

navigation.header

Links in the top bar. Use type: "spacer" to push items before it left and after it right.

"header": [
  { "type": "link", "title": "Home", "to": "/" },
  { "type": "spacer" },
  { "type": "link", "title": "Log in", "to": "https://dashboard.example.com/login", "newTab": true },
  { "type": "link", "title": "Register", "style": "button", "icon": "phosphor/regular/user-plus", "to": "https://...", "newTab": true }
]

Properties: title, type ("link" | "spacer"), to, style ("button" | "link"), icon, newTab

navigation.sidebar

Links at the bottom of the sidebar:

"sidebar": [
  { "title": "Log in", "url": "https://...", "style": "button", "newTab": true }
]

navigation.tabs

Tabs for quick access to sections:

"tabs": [
  { "title": "API", "path": "/api", "icon": "phosphor/regular/plug" }
]

Route Types

Page (type: "page")

Markdown/MDX content from a file:

"/getting-started": {
  "type": "page",
  "title": "Getting Started",
  "filepath": "docs/getting-started.md",
  "description": "Optional SEO description",
  "icon": "phosphor/regular/rocket",
  "showInSidebar": true,
  "layout": { "toc": true, "sidebar": true }
}

Layout: toc (default true), sidebar (default true).

Hidden pages: Set showInSidebar: false to hide a page from the sidebar while keeping it accessible via its direct URL.

OpenAPI (type: "openapi")

API reference from file, Registry, or URL:

File:

"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "icon": "phosphor/regular/plug"
}

Registry:

"/api": {
  "type": "openapi",
  "title": "My API",
  "namespace": "my-organization",
  "slug": "your-api"
}

URL:

"/api": {
  "type": "openapi",
  "title": "My API",
  "url": "https://example.com/openapi.json"
}

Display modes: folder (default), flat, nested.

Single page mode: Set singlePage: true to render all operations on a single page instead of creating separate pages for each operation:

"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "singlePage": true
}

API Reference options (authentication, theme, etc.) go in a config object — same options as the API Reference configuration.

Group (type: "group")

Collapsible section with children:

"/products": {
  "type": "group",
  "title": "Products",
  "mode": "flat",
  "icon": "phosphor/regular/package",
  "children": {
    "/docs": { "type": "page", "title": "Documentation", "filepath": "docs/documentation.md" },
    "/api": { "type": "openapi", "title": "API Reference", "filepath": "openapi.yaml" }
  }
}

Modes: flat, nested, folder (default).

Folder landing pages: Add a page property to make clicking the folder navigate to a page:

"/company": {
  "type": "group",
  "title": "Company",
  "mode": "folder",
  "page": { "type": "page", "title": "About Us", "filepath": "docs/company/index.md" },
  "children": {
    "/team": { "type": "page", "title": "Our Team", "filepath": "docs/company/team.md" }
  }
}

Default open state: Use open: true to expand a folder by default.

Link (type: "link")

External URL:

"/github": {
  "type": "link",
  "title": "GitHub",
  "url": "https://github.com/org/repo",
  "icon": "phosphor/regular/github-logo"
}

---

siteConfig

branding

Logo — single URL or per mode:

"logo": "https://example.com/logo.svg"
// or
"logo": {
  "darkMode": "https://example.com/logo-dark.svg",
  "lightMode": "https://example.com/logo-light.svg"
}

Theme — one of: default, alternate, moon, purple, solarized, bluePlanet, deepSpace, saturn, kepler, mars, laserwave, none

"theme": "purple"

domain

Subdomain (free): https://<subdomain>.apidocumentation.com

"subdomain": "your-docs"

Custom domain (Pro): https://docs.example.com

"customDomain": "docs.example.com"

Subpath — for multiple projects on same domain:

"subpath": "/guides"

layout

"layout": {
  "toc": true,
  "header": true
}

head

Inject scripts, styles, meta tags, and links:

"head": {
  "title": "My Documentation",
  "meta": [
    { "name": "description", "content": "API documentation" },
    { "property": "og:image", "content": "https://example.com/og.png" }
  ],
  "styles": [{ "path": "docs/assets/custom.css", "tagPosition": "head" }],
  "scripts": [{ "path": "docs/assets/analytics.js", "tagPosition": "bodyClose" }],
  "links": [{ "rel": "icon", "href": "/favicon.png" }]
}

For scripts and styles: path relative to config root. For links (favicon): root-relative (/favicon.png).

tagPosition: "head" | "bodyOpen" | "bodyClose".

footer

"footer": {
  "filepath": "docs/footer.html",
  "belowSidebar": true
}

routing

Redirects:

"routing": {
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/old-path/:wildcard", "to": "/new-path" },
    { "from": "/old-path/:pathMatch(.*)*", "to": "/new-path" }
  ]
}

Path patterns:

"routing": {
  "guidePathPattern": "/docs/:slug",
  "referencePathPattern": "/api/:slug"
}

---

assetsDir

Relative path to assets folder. Assets are served from site root.

"assetsDir": "docs/assets"

In Markdown: ![Image](/screenshot.png) or ![Image](../assets/screenshot.png).

In siteConfig.head: use full path relative to config root for scripts/styles; root-relative for links.

---

Migration from Docs 1.0

Docs 1.0 used guides and references arrays. Docs 2.0 uses navigation.routes.

Upgrade:

npx @scalar/cli project upgrade

Check result:

npx @scalar/cli project preview

---

CLI Commands

---

Versions

Use versions instead of navigation to create multi-version documentation.

A version with the key default is required — it is the version shown by default. Additional versions (for example v1) can use any identifier and appear in the version selector. Inside each version's routes, wrap pages in a top-level group so they render correctly in the sidebar.

{
  "scalar": "2.0.0",
  "versions": {
    "default": {
      "title": "Version 2.0",
      "routes": {
        "/": {
          "type": "group",
          "title": "Documentation",
          "children": {
            "/": { "type": "page", "title": "Intro", "filepath": "docs/v2/intro.md" },
            "/api": { "type": "openapi", "title": "API", "filepath": "docs/v2/openapi.yaml" }
          }
        }
      }
    },
    "v1": {
      "title": "Version 1.0",
      "routes": {
        "/": {
          "type": "group",
          "title": "Documentation",
          "children": {
            "/": { "type": "page", "title": "Intro", "filepath": "docs/v1/intro.md" },
            "/api": { "type": "openapi", "title": "API", "filepath": "docs/v1/openapi.yaml" }
          }
        }
      }
    }
  }
}

Each version entry supports: title, routes (required), header, sidebar, tabs.

---

Common Patterns

Multi-project on same domain: Same customDomain or subdomain, different subpath per repo.

MDX: Use .mdx extension in filepath; same structure as Markdown pages.

Hide TOC on a page: "layout": { "toc": false } on that route.

API Reference auth: Add config under the openapi route with authentication (same options as API Reference config).

Custom domain DNS: CNAME host docs → dns.scalar.com (DNS-only, no proxy).

---

References

• Docs Getting Started
• Docs Starter Kit
• Configuration reference
• Navigation
• Versions
• Site config
• Themes
• Domains
• Redirects