// Skill for writing and updating scalar.config.json — Scalar Docs configuration reference for users and LLMs.
| name | scalar-docs |
| description | 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" for the latest formatCreate 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) |
versions | object | Multi-version navigation. Use instead of navigation for versioned docs |
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).
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.
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 |
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.
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).
Minimal starter runbook for cloud agents to install dependencies, run packages, execute tests, and troubleshoot the Scalar monorepo quickly.
Build, customize, and troubleshoot OpenAPI mock servers with @scalar/mock-server, including x-handler, x-seed, authentication, and Docker.
Use consistent OpenAPI terminology and definitions when writing documentation, educational material, and tooling guidance.
Write clear, maintainable Vitest and Playwright tests with precise assertions, consistent structure, and strong behavioral coverage.
Write clear, predictable TypeScript and Vue TypeScript code with strong typing, maintainability, and consistent documentation conventions.
Build Vue 3 components with TypeScript and Tailwind using clean structure, composable logic, accessibility, and maintainable patterns.