Back to Details

scalar-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scalar Docs Configuration Skill — scalar.config.json

Scalar Docs配置技能 — 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.
本指南是用于编写和更新
scalar.config.json
的参考文档，该文件是Scalar Docs的核心配置文件。适用于创建、编辑或验证任意项目的Docs配置场景。

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
  • 文件：
    scalar.config.json
    （或
    scalar.config.json5
    ）
  • 位置：默认位于仓库根目录；可在Scalar Dashboard中覆盖路径设置
  • Schema：
    https://registry.scalar.com/@scalar/schemas/config
    — 当
    json.schemaDownload.enable
    设为true时，可在VS Code/Cursor中启用自动补全功能
  • 版本：最新格式请使用
    "scalar": "2.0.0"

Quick Start

快速开始

Create a minimal config:
bash
npx @scalar/cli project init
Minimal structure:
json
{
  "$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
创建最简配置：
bash
npx @scalar/cli project init
最简结构：
json
{
  "$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"
      }
    }
  }
}
验证配置：
npx @scalar/cli project check-config

Root Properties

根属性

PropertyTypeDescription
$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
属性类型描述
$schema
string
用于编辑器自动补全和验证的JSON Schema URL
scalar
string
配置版本，请使用
"2.0.0"
info
object
项目元数据（标题、描述）
navigation
object
导航结构（头部、路由、侧边栏、标签页）
siteConfig
object
站点级设置（域名、主题、头部、Logo、路由）
assetsDir
string
相对于配置根目录的资源文件夹路径

info

info

Project metadata displayed across the site:
json
{
  "info": {
    "title": "My Documentation",
    "description": "Comprehensive guides for our API"
  }
}
站点中展示的项目元数据：
json
{
  "info": {
    "title": "My Documentation",
    "description": "Comprehensive guides for our API"
  }
}

navigation

navigation

All navigation is in 
navigation.routes
. Each route key is the URL path; the value is a config object.
所有导航配置都在
navigation.routes
中。每个路由键为URL路径，对应的值为配置对象。

navigation.header

navigation.header

Links in the top bar. Use 
type: "spacer"
to push items before it left and after it right.
json
"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
顶部导航栏中的链接。使用
type: "spacer"
可将其左侧的项左移、右侧的项右移。
json
"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 }
]
属性：
title
、
type
（
"link"
| 
"spacer"
）、
to
、
style
（
"button"
| 
"link"
）、
icon
、
newTab

navigation.sidebar

navigation.sidebar

Links at the bottom of the sidebar:
json
"sidebar": [
  { "title": "Log in", "url": "https://...", "style": "button", "newTab": true }
]
侧边栏底部的链接：
json
"sidebar": [
  { "title": "Log in", "url": "https://...", "style": "button", "newTab": true }
]

navigation.tabs

navigation.tabs

Tabs for quick access to sections:
json
"tabs": [
  { "title": "API", "path": "/api", "icon": "phosphor/regular/plug" }
]
用于快速访问各板块的标签页：
json
"tabs": [
  { "title": "API", "path": "/api", "icon": "phosphor/regular/plug" }
]

Route Types

路由类型

Page (
type: "page"
)

页面（
type: "page"
）

Markdown/MDX content from a file:
json
"/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.
来自文件的Markdown/MDX内容：
json
"/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 }
}
布局：
toc
（默认
true
）、
sidebar
（默认
true
）。
隐藏页面：设置
showInSidebar: false
可将页面从侧边栏隐藏，但仍可通过直接URL访问。

OpenAPI (
type: "openapi"
)

OpenAPI（
type: "openapi"
）

API reference from file, Registry, or URL:
File:
json
"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "icon": "phosphor/regular/plug"
}
Registry:
json
"/api": {
  "type": "openapi",
  "title": "My API",
  "namespace": "my-organization",
  "slug": "your-api"
}
URL:
json
"/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.
来自文件、Registry或URL的API参考：
文件：
json
"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "icon": "phosphor/regular/plug"
}
Registry：
json
"/api": {
  "type": "openapi",
  "title": "My API",
  "namespace": "my-organization",
  "slug": "your-api"
}
URL：
json
"/api": {
  "type": "openapi",
  "title": "My API",
  "url": "https://example.com/openapi.json"
}
展示模式：
folder
（默认）、
flat
、
nested
。
API参考选项（认证、主题等）需放在
config
对象中——与API Reference配置的选项一致。

Group (
type: "group"
)

分组（
type: "group"
）

Collapsible section with children:
json
"/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).
包含子项的可折叠板块：
json
"/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" }
  }
}
模式：
flat
、
nested
、
folder
（默认）。

Link (
type: "link"
)

链接（
type: "link"
）

External URL:
json
"/github": {
  "type": "link",
  "title": "GitHub",
  "url": "https://github.com/org/repo",
  "icon": "phosphor/regular/github-logo"
}
外部URL：
json
"/github": {
  "type": "link",
  "title": "GitHub",
  "url": "https://github.com/org/repo",
  "icon": "phosphor/regular/github-logo"
}

siteConfig

siteConfig

branding

品牌设置

Logo — single URL or per mode:
json
"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
json
"theme": "purple"
Logo — 单个URL或分模式设置：
json
"logo": "https://example.com/logo.svg"
// 或
"logo": {
  "darkMode": "https://example.com/logo-dark.svg",
  "lightMode": "https://example.com/logo-light.svg"
}
主题 — 可选值：
default
, 
alternate
, 
moon
, 
purple
, 
solarized
, 
bluePlanet
, 
deepSpace
, 
saturn
, 
kepler
, 
mars
, 
laserwave
, 
none
json
"theme": "purple"

domain

域名

Subdomain (free): 
https://<subdomain>.apidocumentation.com
json
"subdomain": "your-docs"
Custom domain (Pro): 
https://docs.example.com
json
"customDomain": "docs.example.com"
Subpath — for multiple projects on same domain:
json
"subpath": "/guides"
子域名（免费）：
https://<subdomain>.apidocumentation.com
json
"subdomain": "your-docs"
自定义域名（Pro版）：
https://docs.example.com
json
"customDomain": "docs.example.com"
子路径 — 同一域名下部署多个项目：
json
"subpath": "/guides"

layout

布局

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

head

头部

Inject scripts, styles, meta tags, and links:
json
"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"
.
注入脚本、样式、元标签和链接：
json
"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" }]
}
对于
scripts
和
styles
：路径为相对于配置根目录的路径。对于
links
（如favicon）：使用根相对路径（
/favicon.png
）。
tagPosition
: 
"head"
| 
"bodyOpen"
| 
"bodyClose"
。

footer

页脚

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

routing

路由

Redirects:
json
"routing": {
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/old-path/:wildcard", "to": "/new-path" },
    { "from": "/old-path/:pathMatch(.*)*", "to": "/new-path" }
  ]
}
Path patterns:
json
"routing": {
  "guidePathPattern": "/docs/:slug",
  "referencePathPattern": "/api/:slug"
}
重定向：
json
"routing": {
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/old-path/:wildcard", "to": "/new-path" },
    { "from": "/old-path/:pathMatch(.*)*", "to": "/new-path" }
  ]
}
路径模式：
json
"routing": {
  "guidePathPattern": "/docs/:slug",
  "referencePathPattern": "/api/:slug"
}

assetsDir

assetsDir

Relative path to assets folder. Assets are served from site root.
json
"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.
资源文件夹的相对路径。资源将从站点根目录提供服务。
json
"assetsDir": "docs/assets"
在Markdown中：
![Image](/screenshot.png)
或 
![Image](../assets/screenshot.png)
。
在
siteConfig.head
中：脚本/样式使用相对于配置根目录的完整路径；链接使用根相对路径。

Migration from Docs 1.0

从Docs 1.0迁移

Docs 1.0 used 
guides
and 
references
arrays. Docs 2.0 uses 
navigation.routes
.
Upgrade:
bash
npx @scalar/cli project upgrade
Check result:
bash
npx @scalar/cli project preview
Docs 1.0使用
guides
和
references
数组。Docs 2.0使用
navigation.routes
。
升级命令：
bash
npx @scalar/cli project upgrade
检查结果：
bash
npx @scalar/cli project preview

CLI Commands

CLI命令

CommandDescription
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
命令描述
npx @scalar/cli project init
创建scalar.config.json
npx @scalar/cli project check-config
验证配置
npx @scalar/cli project preview
本地预览（端口7971）
npx @scalar/cli project publish
从本地文件发布
npx @scalar/cli project publish --github
从关联的GitHub仓库发布
npx @scalar/cli project upgrade
从Docs 1.0迁移

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).
同一域名下多项目： 相同的
customDomain
或
subdomain
，每个仓库使用不同的
subpath
。
MDX： 在
filepath
中使用
.mdx
扩展名；结构与Markdown页面一致。
隐藏页面目录： 在对应路由中设置
"layout": { "toc": false }
。
API参考认证： 在openapi路由下添加包含
authentication
的
config
对象（与API Reference配置选项一致）。
自定义域名DNS： 将CNAME主机
docs
指向
dns.scalar.com
（仅DNS，无需代理）。

References

参考链接