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

The header only renders when this array has at least one item, and it is where the logo goes. A lone { "type": "spacer" } is enough to get a header with just the logo.

navigation.sidebar

Links at the bottom of the sidebar:

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

navigation.tabs

Tabs for quick access to sections:

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

Tabs and a header work together, and neither requires the other. With tabs but no header, the logo renders in the tab bar.

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

The logo renders on the first surface the site has: header (if navigation.header has items) → tabs (if navigation.tabs but no header) → sidebar (if neither). A page that hides all three via layout does not render it at all. With no logo set, info.title renders in the same place.

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

"theme": "purple"

Social card — point og.imageTemplate at a TSX/JSX template in the project to replace the generated share image. The path is relative to the config file and must stay inside the project.

"og": {
  "imageTemplate": "./og/card.tsx"
}

The template default-exports a pure function taking { title, description?, breadcrumb?, path, colors, logo, mode } and returning JSX. It is drawn by Satori: flexbox only, inline styles only, no packages imported. An og:image in siteConfig.head.meta overrides it site-wide.

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