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/scalarscalar.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 youve 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 个根属性如下属性类型说明$schemastring用于编辑器自动补全与校验的 JSON Schema URLscalarstring配置版本号最新格式使用2.0.0infoobject项目元数据title、descriptionnavigationobject导航结构header 链接、routes、sidebar、tabs详见 Navigationversionsobject多版本导航结构用于版本化文档时替代navigation详见 VersionssiteConfigobject站点级配置domain、theme、head、logoassetsDirstring资源目录路径相对仓库根目录其中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 } ] } } }官方属性表属性类型说明themestring视觉主题default、alternate、moon、purple、solarized、bluePlanet、deepSpace、saturn、kepler、marslogoobject深色/浅色模式各自的 Logo URLheadobject自定义 scripts、styles、meta 标签与 linksroutingobjectURL 重定向配置subpathstring多项目部署时的 URL 子路径如/guides、/apicolorSchemeobject明暗模式设置见 Sitelayoutobject全局布局选项含搜索配置见 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。footersiteConfig.footer.filepath指向一个自定义 HTML 片段本仓库为 documentation/footer.html见 scalar.config.json#L81-L83。rsssiteConfig.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.positionheader或sidebar这些细节完整收录在 site-config.md 中。主题取值与自定义主题的说明见 themes.md重定向的独立文档见 redirects.md。navigation路由、header 与 sidebarnavigation的详细字段定义在 Navigation 中这里给出与本主题直接相关的要点并以本仓库配置作为验证样本routes以 URL 路径为键、配置对象为值。路由项的type主要有page指向本地 Markdown用filepath、openapiAPI Reference用url或本地文件、group分组用children等icon接受 Phosphor / Simple Icons 的图标键或自定义 URL。本仓库首页路由就是一个groupchildren下的键挂首页page并带了逐页的layout覆盖如toc: false见 scalar.config.json#L1029-L1041。header数组定义顶栏内容。顶层项可用alignstart/center/end默认start选择区域style: button渲染为按钮样式{type: spacer}是分隔占位项。本仓库 header 中Home、Docs、Pricing靠左spacer之后是一个group下拉框ResourcesLog 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与navigationheader 外链 分组路由 两种路由类型{ $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 } }仓库 2Guides{ siteConfig: { customDomain: docs.example.com, subpath: /guides } }仓库 3API Reference{ siteConfig: { customDomain: docs.example.com, subpath: /api } }每个仓库独立部署但所有项目都出现在同一域名下各自的子路径中。注意前提subpath项目必须放在非根路径根路径由主文档占据三个仓库互不依赖改动任一仓库只需重新部署该项目。小结与延伸阅读scalar.config.json用单一 JSON 文件承载了 Scalar Docs 的站点元数据、导航、外观与部署策略infonavigation决定有什么内容、怎么组织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等命令组【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考