Skill for writing and updating scalar.config.json — Scalar Docs configuration reference for users and LLMs.
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.
scalar.config.json (or scalar.config.json5)https://registry.scalar.com/@scalar/schemas/config — enables autocomplete in VS Code/Cursor when json.schemaDownload.enable is true"scalar": "2.0.0"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
| Property | Type | Description |
|---|---|---|
$schema | string | JSON Schema URL for editor autocomplete and validation |
scalar | string | Configuration version. Use "2.0.0" |
info | object | Project metadata (title, description) |
navigation | object | Navigation structure (header, routes, sidebar, tabs) |
siteConfig | object | Site-level settings (domain, theme, head, logo, routing) |
assetsDir | string | Relative path to assets folder from config root |
Project metadata displayed across the site:
{
"info": {
"title": "My Documentation",
"description": "Comprehensive guides for our API"
}
}
All navigation is in navigation.routes. Each route key is the URL path; the value is a config object.
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
Links at the bottom of the sidebar:
"sidebar": [
{ "title": "Log in", "url": "https://...", "style": "button", "newTab": true }
]
Tabs for quick access to sections:
"tabs": [
{ "title": "API", "path": "/api", "icon": "phosphor/regular/plug" }
]
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.
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.
API Reference options (authentication, theme, etc.) go in a config object — same options as the API Reference configuration.
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).
type: "link")External URL:
"/github": {
"type": "link",
"title": "GitHub",
"url": "https://github.com/org/repo",
"icon": "phosphor/regular/github-logo"
}
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"
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": {
"toc": true,
"header": true
}
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": {
"filepath": "docs/footer.html",
"belowSidebar": true
}
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"
}
Relative path to assets folder. Assets are served from site root.
"assetsDir": "docs/assets"
In Markdown:  or .
In siteConfig.head: use full path relative to config root for scripts/styles; root-relative for links.
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
| Command | Description |
|---|---|
npx @scalar/cli project init | Create scalar.config.json |
npx @scalar/cli project check-config | Validate config |
npx @scalar/cli project preview | Local preview (port 7971) |
npx @scalar/cli project publish | Publish from local files |
npx @scalar/cli project publish --github | Publish from linked GitHub repo |
npx @scalar/cli project upgrade | Migrate from Docs 1.0 |
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).