scalar-docs

Scalar Docs 配置技能 — scalar.config.json

编写和更新 scalar.config.json 的参考文档。它是 Scalar Docs 的中央配置文件。创建、编辑或验证任何项目的 Docs 配置时，请使用此文档。

概述

• 文件：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"

快速开始

创建一个最简配置：

npx @scalar/cli project init

最简结构：

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

---

根属性

属性	类型	描述
$schema	string	用于编辑器自动补全和验证的 JSON Schema URL
scalar	string	配置版本。使用 "2.0.0"
info	object	项目元数据（标题、描述）
navigation	object	导航结构（页眉、路由、侧边栏、标签页）
versions	object	多版本导航。用于替代版本化文档中的 navigation
siteConfig	object	网站级设置（域名、主题、head、徽标、路由）
assetsDir	string	从配置根目录开始的资源文件夹相对路径

---

info

在整个网站中显示的项目元数据：

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

---

navigation

所有导航都位于 navigation.routes 中。每个路由键都是 URL 路径；其值是一个配置对象。

navigation.header

顶部栏中的链接。使用 type: "spacer" 将其前面的项目推到左侧，将其后面的项目推到右侧。

"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

只有当此数组至少包含一个项目时，页眉才会显示，徽标也位于此处。仅使用 { "type": "spacer" } 就足以显示只有徽标的页眉。

navigation.sidebar

侧边栏底部的链接：

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

navigation.tabs

用于快速访问各个部分的标签页：

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

标签页可以与页眉配合使用，二者互不依赖。只有标签页而没有页眉时，徽标会显示在标签栏中。

路由类型

页面（type: "page"）

来自文件的 Markdown/MDX 内容：

"/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"）

来自文件、Registry 或 URL 的 API 参考文档：

文件：

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

显示模式：folder（默认）、flat、nested。

单页模式： 设置 singlePage: true，即可将所有操作呈现在同一页面，而不是为每个操作创建单独的页面：

"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "singlePage": true
}

API 参考文档选项（身份验证、主题等）应放在 config 对象中——与 API Reference 配置中的选项相同。

分组（type: "group"）

包含子项的可折叠部分：

"/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（默认）。

文件夹着陆页： 添加 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" }
  }
}

默认展开状态： 使用 open: true 默认展开文件夹。

链接（type: "link"）

外部 URL：

"/github": {
  "type": "link",
  "title": "GitHub",
  "url": "https://github.com/org/repo",
  "icon": "phosphor/regular/github-logo"
}

---

siteConfig

branding

徽标 — 单个 URL 或按模式设置：

"logo": "https://example.com/logo.svg"
// or
"logo": {
  "darkMode": "https://example.com/logo-dark.svg",
  "lightMode": "https://example.com/logo-light.svg"
}

徽标会显示在网站的第一个可用区域：页眉（如果 navigation.header 有项目）→ 标签页（如果有 navigation.tabs，但没有页眉）→ 侧边栏（如果两者都没有）。通过 layout 隐藏这三个区域的页面不会显示徽标。未设置 logo 时，info.title 会显示在同一位置。

主题 — 可选值：default、alternate、moon、purple、solarized、bluePlanet、deepSpace、saturn、kepler、mars、laserwave、none

"theme": "purple"

社交卡片 — 将 og.imageTemplate 指向项目中的 TSX/JSX 模板，以替换生成的分享图片。路径相对于配置文件，且必须位于项目目录内。

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

模板默认导出一个纯函数，该函数接收 { title, description?, breadcrumb?, path, colors, logo, mode } 并返回 JSX。它由 Satori 绘制：仅支持 flexbox 和内联样式，不能导入软件包。在 siteConfig.head.meta 中设置的 og:image 会在整个站点范围内覆盖它。

domain

子域名（免费）：https://<subdomain>.apidocumentation.com

"subdomain": "your-docs"

自定义域名（Pro）：https://docs.example.com

"customDomain": "docs.example.com"

子路径 — 用于在同一域名上托管多个项目：

"subpath": "/guides"

layout

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

head

注入脚本、样式、元标签和链接：

"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.png）。

tagPosition："head" | "bodyOpen" | "bodyClose"。

footer

"footer": {
  "filepath": "docs/footer.html"
}

rss

为更新日志或博客发布 RSS 订阅源，方便读者订阅。文件写入 <path>/rss.xml——位于 /changelog 的更新日志会将订阅源发布在 /changelog/rss.xml。

"rss": {
  "path": "/changelog",
  "title": "Scalar Changelog",
  "description": "Every Scalar release, as a feed"
}

属性	类型	必填	说明
path	string	是	更新日志路由，例如 /changelog。不能包含 .. 片段
title	string	否	订阅源标题。默认使用网站标题加上 Changelog
description	string	否	订阅源描述
entries	string	否	headings（默认）或 pages——见下文

若要发布多个订阅源，请将 rss 设置为这些对象组成的列表。每个对象都需要唯一的 path，并会写入 <path>/rss.xml：

"rss": [
  { "path": "/changelog", "title": "Scalar Changelog" },
  { "path": "/blog", "title": "Scalar Blog" }
]

条目取自 path 对应页面或其下任意页面中带日期的标题（## 1.2.0 (2026-07-24)），合并后按时间从新到旧排列。只有最顶层的带日期标题级别会开始新条目；更深层的标题（无论是否带日期）都会并入上面的版本。隐藏页面会被跳过。每个页面都会通过 <link rel="alternate" type="application/rss+xml"> 标签声明订阅源，path 下的页面会在页面页眉显示订阅按钮。

将 entries 设置为 pages 可用于博客：path 下每个在 frontmatter 中包含 date（date: 2026-07-24）的页面都会成为一条目，标题使用页面标题。没有 date 的页面（索引页、草稿）会被跳过。更新日志请使用默认值 headings。

routing

重定向：

"routing": {
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/old-path/:wildcard", "to": "/new-path" },
    { "from": "/old-path/:pathMatch(.*)*", "to": "/new-path" }
  ]
}

路径模式：

"routing": {
  "guidePathPattern": "/docs/:slug",
  "referencePathPattern": "/api/:slug"
}

---

assetsDir

资源文件夹的相对路径。资源会从网站根目录提供。

"assetsDir": "docs/assets"

在 Markdown 中：![Image](/screenshot.png) 或 ![Image](../assets/screenshot.png)。

在 siteConfig.head 中：脚本和样式使用相对于配置根目录的完整路径；链接使用相对于根目录的路径。

---

从 Docs 1.0 迁移

Docs 1.0 使用 guides 和 references 数组。Docs 2.0 使用 navigation.routes。

升级：

npx @scalar/cli project upgrade

检查结果：

npx @scalar/cli project preview

---

CLI 命令

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

---

版本

使用 versions 而非 navigation 创建多版本文档。

必须有一个键为 default 的版本——它是默认显示的版本。其他版本（例如 v1）可以使用任意标识符，并显示在版本选择器中。在每个版本的 routes 中，将页面放在顶层 group 下，以便它们在侧边栏中正确显示。

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

每个版本条目支持：title、routes（必填）、header、sidebar、tabs。

---

常见模式

同一域名下的多项目： 使用相同的 customDomain 或 subdomain，并为每个仓库设置不同的 subpath。

MDX： 在 filepath 中使用 .mdx 扩展名；结构与 Markdown 页面相同。

在页面上隐藏目录： 在对应路由中设置 "layout": { "toc": false }。

API Reference 身份验证： 在 openapi 路由下添加 config，并设置 authentication（选项与 API Reference 配置相同）。

自定义域名 DNS： CNAME 主机 docs → dns.scalar.com（仅 DNS，不使用代理）。

---

参考资料

• Docs 入门指南
• Docs Starter Kit
• 配置参考
• 导航
• 版本
• 站点配置
• 主题
• 域名
• 重定向