Scalar
Overview

scalar.config.json

Creating the configuration file#

You can create a configuration file manually or use the Scalar CLI:

npx @scalar/cli project init

This command creates a scalar.config.json file in your current directory with a basic structure to get you started.

Basic structure#

Here is a minimal configuration to get started:

{
  "$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"
      }
    }
  }
}

Autocomplete in VS Code and Cursor#

To get autocomplete and validation in your editor, enable JSON schema downloads in VS Code (or Cursor):

// .vscode/settings.json
{
  "json.schemaDownload.enable": true
  "json.schemaDownload.trustedDomains": {
    "https://registry.scalar.com/": true,
  }
}

The $schema property in your configuration file tells the editor where to find the schema:

// scalar.config.json
{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config"
}

Your editor will now provide autocomplete suggestions and highlight invalid properties.

Configuration reference#

Root properties#

Property Type Description
$schema string JSON Schema URL for editor autocomplete and validation
scalar string Configuration version. Use "2.0.0" for the latest format
info object Project metadata (title, description)
navigation object Navigation structure (header links, routes, sidebar, tabs). See Navigation for details
versions object Multi-version navigation structure. Use instead of navigation for versioned docs. See Versions
siteConfig object Site-level configuration (domain, theme, head, logo)
assetsDir string Path to the assets directory (relative to repository root)

info#

Project metadata displayed in various places:

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

siteConfig#

Configure your site's domain, appearance, and custom assets:

{
  "siteConfig": {
    "subdomain": "acme",
    "customDomain": "docs.example.com",
    "theme": "purple",
    "logo": {
      "darkMode": "https://example.com/logo-dark.svg",
      "lightMode": "https://example.com/logo-light.svg"
    },
    "head": {
      "scripts": [{ "path": "assets/analytics.js" }],
      "styles": [{ "path": "assets/custom.css" }],
      "meta": [{ "name": "description", "content": "My docs description" }],
      "links": [{ "rel": "icon", "href": "/favicon.png" }]
    },
    "routing": {
      "redirects": [
        { "from": "/old-path", "to": "/new-path" }
      ]
    }
  }
}

siteConfig properties#

Property Type Description
theme string Visual theme (default, alternate, moon, purple, solarized, bluePlanet, deepSpace, saturn, kepler, mars)
logo object Logo URLs for dark and light modes
head object Custom scripts, styles, meta tags, and links
routing object URL redirects configuration
subpath string URL subpath for multi-project deployments (e.g., /guides, /api)
colorScheme object Light/dark mode appearance settings. See Site
layout object Global layout options including search configuration. See Site

For detailed navigation configuration, see Navigation.

Full example#

Here is a more complete example showing common configuration options:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    "title": "Acme API Documentation",
    "description": "Everything you need to integrate with Acme"
  },
  "assetsDir": "docs/assets",
  "siteConfig": {
    "subdomain": "acme",
    "theme": "default",
    "logo": {
      "darkMode": "https://example.com/logo-dark.svg",
      "lightMode": "https://example.com/logo-light.svg"
    },
    "head": {
      "meta": [
        { "name": "description", "content": "Acme API documentation and guides" }
      ],
      "links": [
        { "rel": "icon", "href": "/favicon.png" }
      ]
    }
  },
  "navigation": {
    "header": [
      { "type": "link", "title": "Dashboard", "to": "https://dashboard.example.com" }
    ],
    "routes": {
      "/": {
        "type": "group",
        "title": "Acme",
        "children": {
          "": {
            "type": "page",
            "title": "Introduction",
            "filepath": "docs/introduction.md",
            "icon": "phosphor/regular/house"
          },
          "/api": {
            "type": "openapi",
            "title": "API Reference",
            "url": "https://example.com/openapi.yaml",
            "icon": "phosphor/regular/notebook"
          }
        }
      }
    }
  }
}

File location#

By default, the scalar.config.json file should be placed in the root of your GitHub repository. If you need to place it in a different location, you can configure the path in the Scalar Dashboard.

Deploying multiple projects on the same domain#

You can deploy multiple documentation projects on the same subdomain or custom domain by using the subpath property. Each project lives in its own repository with its own scalar.config.json, but they share the same domain.

For example, you might want to have:

  • docs.example.com/ — Your main documentation
  • docs.example.com/guides/ — Tutorial guides
  • docs.example.com/api/ — API reference

To set this up, create a separate repository for each project and configure them with the same subdomain or customDomain but a different subpath:

Repository 1: Main documentation

// scalar.config.json
{
  "siteConfig": {
    "customDomain": "docs.example.com"
  }
}

Repository 2: Guides

// scalar.config.json
{
  "siteConfig": {
    "customDomain": "docs.example.com",
    "subpath": "/guides"
  }
}

Repository 3: API reference

// scalar.config.json
{
  "siteConfig": {
    "customDomain": "docs.example.com",
    "subpath": "/api"
  }
}

Each repository is deployed independently, but all projects appear under the same domain with their respective subpaths.

Updated

Was this page helpful?