Scalar Docs 配置指南：scalar.config.json 完整解析与同域多项目部署-创锋一号

Scalar Docs 配置指南：scalar.config.json 完整解析与同域多项目部署

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar

scalar.config.json是 Scalar Docs 的中心配置文件，它在一个 JSON 文件里统一定义了文档站的元数据（info）、导航结构（navigation）、站点级设置（siteConfig）与部署选项（子域、自定义域名、subpath）。本篇基于 Scalar 仓库中的官方配置文档 scalar.config.json.md 展开，完整覆盖从 CLI 初始化、编辑器自动补全到根属性参考的全部细节，并结合本仓库根目录那份真实在用的 4787 行 scalar.config.json 逐段验证每个配置项的实际用法，读完即可独立完成一套文档站的配置与部署。

文件定位与基本结构

文件放在哪里

按官方文档约定，scalar.config.json默认应放在GitHub 仓库根目录。如果你的文件放在其他位置，可以在 Scalar Dashboard 中配置实际路径。本仓库即为标准示例：配置文件位于仓库根目录，而它渲染的文档内容（Markdown）集中在documentation/guides/下，两者通过配置中的filepath字段关联。

两种创建方式

可以手动创建文件，也可以使用 Scalar CLI 初始化：

npx @scalar/cli project init

该命令会在当前目录生成一份带基础结构的scalar.config.json。CLI 的完整命令清单（含project、document、registry等命令组）见 CLI 命令文档。

最小可用配置

官方文档给出的最小结构如下，包含info和一个指向 Markdown 页面的根路由：

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

本仓库自己的配置开头几行 scalar.config.json#L1-L8 与这个最小结构完全同构：$schema、scalar: "2.0.0"、info、以及指向documentation/assets的assetsDir，只是navigation部分扩展到了数万个字符。

在 VS Code 与 Cursor 中启用自动补全

配置文件的$schema属性会告诉编辑器去哪里取 JSON Schema，从而提供属性补全和非法属性高亮：

// scalar.config.json { "$schema": "https://registry.scalar.com/@scalar/schemas/config" }

由于该 Schema 托管在registry.scalar.com，需要在编辑器中开启 JSON Schema 下载能力。以 VS Code（或 Cursor）为例，在.vscode/settings.json中加入：

{ "json.schemaDownload.enable": true, "json.schemaDownload.trustedDomains": { "https://registry.scalar.com/": true } }

配置完成后，编辑器即可对配置项提供补全建议并标出无效属性。

根属性参考（Configuration Reference）

官方文档定义的 7 个根属性如下：

属性	类型	说明
`$schema`	`string`	用于编辑器自动补全与校验的 JSON Schema URL
`scalar`	`string`	配置版本号，最新格式使用`"2.0.0"`
`info`	`object`	项目元数据（title、description）
`navigation`	`object`	导航结构（header 链接、routes、sidebar、tabs），详见 Navigation
`versions`	`object`	多版本导航结构，用于版本化文档时替代`navigation`，详见 Versions
`siteConfig`	`object`	站点级配置（domain、theme、head、logo）
`assetsDir`	`string`	资源目录路径（相对仓库根目录）

其中info是展示在各处的项目元数据：

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

siteConfig：站点外观、注入与路由

siteConfig配置站点的域名、外观与自定义资源。官方示例：

{ "siteConfig": { "subdomain": "acme", "customDomain": "docs.example.com", "theme": "purple", "logo": { "darkMode": "https://example.com/logo-dark.svg", "lightMode": "https://example.com/logo-light.svg" }, "head": { "scripts": [{ "path": "assets/analytics.js" }], "styles": [{ "path": "assets/custom.css" }], "meta": [{ "name": "description", "content": "My docs description" }], "links": [{ "rel": "icon", "href": "/favicon.png" }] }, "routing": { "redirects": [ { "from": "/old-path", "to": "/new-path" } ] } } }

官方属性表：

属性	类型	说明
`theme`	`string`	视觉主题（`default`、`alternate`、`moon`、`purple`、`solarized`、`bluePlanet`、`deepSpace`、`saturn`、`kepler`、`mars`）
`logo`	`object`	深色/浅色模式各自的 Logo URL
`head`	`object`	自定义 scripts、styles、meta 标签与 links
`routing`	`object`	URL 重定向配置
`subpath`	`string`	多项目部署时的 URL 子路径（如`/guides`、`/api`）
`colorScheme`	`object`	明暗模式设置，见 Site
`layout`	`object`	全局布局选项（含搜索配置），见 Site

结合仓库源码理解各子项的实际形态

仓库自带的 scalar.config.json#L9-L92 是一份"生产级"siteConfig，恰好演示了上述大部分子项的组合用法：

head.scripts：同时支持本地path与远程url，并用defer/async控制加载方式。本仓库注入 6 个本地脚本（documentation/assets/landing.js、powered-by.js、fathom.js等）时均设置"defer": true，还有一个远程脚本设置"async": true，见 scalar.config.json#L12-L42。按 Site 配置文档的说明，未声明async/defer的脚本默认在<head>中同步加载并阻塞首屏渲染，因此分析、统计类脚本应显式加上defer或async。
head.meta：除name外还支持property键，用于 Open Graph / Twitter Card 标签（如og:site_name、twitter:card），见 scalar.config.json#L48-L69。
footer：siteConfig.footer.filepath指向一个自定义 HTML 片段，本仓库为 documentation/footer.html，见 scalar.config.json#L81-L83。
rss：siteConfig.rss可为 changelog 发布 RSS 源，本仓库配置为path: "/resources/changelog"并带title、description，见 scalar.config.json#L88-L92。
routing.redirects：本仓库配置了约 60 条重定向规则，用于旧文档结构（/scalar/scalar-docs/...、/scalar/sdks/...）向新结构（/products/docs/...、/products/sdk-generator/...）的迁移。其中一条恰好指向本主题所在的配置页：/scalar/scalar-docs/github-sync→/products/docs/configuration/scalar.config.json，见 scalar.config.json#L93-L154。这展示了redirects在站点改版时的典型用途——保持旧 URL 可达。

此外，logo支持单 URL 字符串或{darkMode, lightMode}对象两种形态；不配置logo时会退化为显示info.title。colorScheme.default可取light/dark/system（默认system），配合showToggle（默认true）可强制固定明暗模式；layout可全局控制toc、header、pageTitle、pageActions及search.enabled/search.position（header或sidebar），这些细节完整收录在 site-config.md 中。主题取值与自定义主题的说明见 themes.md，重定向的独立文档见 redirects.md。

navigation：路由、header 与 sidebar

navigation的详细字段定义在 Navigation 中，这里给出与本主题直接相关的要点，并以本仓库配置作为验证样本：

routes：以 URL 路径为键、配置对象为值。路由项的type主要有page（指向本地 Markdown，用filepath）、openapi（API Reference，用url或本地文件）、group（分组，用children）等；icon接受 Phosphor / Simple Icons 的图标键或自定义 URL。本仓库首页路由就是一个group，children下的""键挂首页page，并带了逐页的layout覆盖（如"toc": false），见 scalar.config.json#L1029-L1041。
header：数组定义顶栏内容。顶层项可用align（start/center/end，默认start）选择区域，style: "button"渲染为按钮样式；{"type": "spacer"}是分隔占位项。本仓库 header 中Home、Docs、Pricing靠左，spacer之后是一个group下拉框（Resources），Log in与按钮样式的Register靠右，见 scalar.config.json#L922-L1015。
group 下拉与分栏：group的children是 link 数组；给 child 加section字段可把下拉内容按标题分栏（官方称为 Mega Menus）。本仓库Resources下拉内的链接按section: "Resources"/section: "Company"分了两栏，见 scalar.config.json#L943-L1003。
sidebar：数组形式，常用于放联系与 CTA 链接。本仓库 sidebar 仅两项：mailto:联系邮箱与带newTab: true的 Demo 预约链接，见 scalar.config.json#L1016-L1028。

对于多版本文档，则改用根级的versions属性替代navigation，规则见 Versions。

完整配置示例

官方文档给出的较完整示例，覆盖assetsDir、siteConfig（子域、主题、logo、head）与navigation（header 外链 + 分组路由 + 两种路由类型）：

{ "$schema": "https://registry.scalar.com/@scalar/schemas/config", "scalar": "2.0.0", "info": { "title": "Acme API Documentation", "description": "Everything you need to integrate with Acme" }, "assetsDir": "docs/assets", "siteConfig": { "subdomain": "acme", "theme": "default", "logo": { "darkMode": "https://example.com/logo-dark.svg", "lightMode": "https://example.com/logo-light.svg" }, "head": { "meta": [ { "name": "description", "content": "Acme API documentation and guides" } ], "links": [ { "rel": "icon", "href": "/favicon.png" } ] } }, "navigation": { "header": [ { "type": "link", "title": "Dashboard", "to": "https://dashboard.example.com" } ], "routes": { "/": { "type": "group", "title": "Acme", "children": { "": { "type": "page", "title": "Introduction", "filepath": "docs/introduction.md", "icon": "phosphor/regular/house" }, "/api": { "type": "openapi", "title": "API Reference", "url": "https://example.com/openapi.yaml", "icon": "phosphor/regular/notebook" } } } } } }

这个示例与仓库真实配置形成了很好的对照："": { ... }的空串键表示组内首页路由；type: "openapi"的路由直接挂载远程 OpenAPI 文档；filepath/assetsDir均为相对仓库根目录的路径——本仓库的assetsDir: "documentation/assets"与根级配置 scalar.config.json#L8 一致。

在同一域名部署多个文档项目

官方文档提供了用subpath实现"一个域名、多个文档项目"的方案：每个项目独立仓库、独立scalar.config.json，但共享同一个subdomain或customDomain，各自声明不同subpath。

典型布局：

docs.example.com/— 主文档
docs.example.com/guides/— 教程指南
docs.example.com/api/— API Reference

三个仓库的配置分别为：

仓库 1：主文档

{ "siteConfig": { "customDomain": "docs.example.com" } }

仓库 2：Guides

{ "siteConfig": { "customDomain": "docs.example.com", "subpath": "/guides" } }

仓库 3：API Reference

{ "siteConfig": { "customDomain": "docs.example.com", "subpath": "/api" } }

每个仓库独立部署，但所有项目都出现在同一域名下各自的子路径中。注意前提：subpath项目必须放在"非根路径"，根路径由主文档占据；三个仓库互不依赖，改动任一仓库只需重新部署该项目。

小结与延伸阅读

scalar.config.json用单一 JSON 文件承载了 Scalar Docs 的站点元数据、导航、外观与部署策略：info+navigation决定"有什么内容、怎么组织"，siteConfig决定"挂在什么域名、长什么样"，subpath决定"与哪些兄弟项目共存"。本仓库的 scalar.config.json 是一份可直接研读的生产级样本（含 4787 行的完整 header/routes/redirects 配置），配套文档则构成完整体系：

navigation.md — routes/header/tabs/sidebar 全字段参考
site-config.md — logo、theme、colorScheme、layout、head、footer、rss、routing 细则
versions.md — 多版本文档导航
redirects.md — 重定向规则
themes.md — 主题说明
CLI 命令文档 —scalar project等命令组

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析