Scalar Docs 快速上手：从 Markdown 指南到可部署 API 文档站

Scalar Docs 快速上手：从 Markdown 指南到可部署 API 文档站

【免费下载链接】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 官方文档documentation/guides/docs/getting-started.md，带你用最少步骤创建并发布一个文档站：用 Markdown 或 MDX 撰写指南，为 OpenAPI 文档自动生成可交互的 API 参考，最终从 GitHub、命令行或网页编辑器完成部署。读完后，你将掌握三步建站流程、核心配置文件scalar.config.json的结构，以及本地预览、CLI 发布、GitHub Actions 自动部署三条路径的具体用法与可验证依据。

三步创建文档站

Scalar Docs 把"从空目录到上线"拆成三个环节。下面每一步都给出可直接复制的命令与配置片段。

第 1 步：启动一个项目

你可以从 Dashboard、Starter Kit，或任意包含scalar.config.json文件的文件夹开始。本地预览命令是：

npx @scalar/cli project preview

该命令会在http://localhost:7970启动一个实时预览服务，你每保存一次 Markdown 文件，改动都会即时反映在页面上（端口见 Starter Kit）。如果想让配置结构更规范，可以先用 CLI 初始化一份基础配置：

npx @scalar/cli project init

project init会在当前目录生成一份scalar.config.json，作为后续所有配置的地基（详见 scalar.config.json 参考）。

第 2 步：添加指南与 API 文档

指南用 Markdown 或 MDX 编写；API 参考则由 OpenAPI/AsyncAPI 文档自动生成。两者的挂载点都在scalar.config.json的navigation.routes对象里——以 URL 路径作为键、配置对象作为值：

{ "navigation": { "routes": { "/getting-started": { "type": "page", "filepath": "docs/getting-started.md" } } } }

type: "page"表示渲染一份仓库里的 Markdown 文件；若把type换成"openapi"或"asyncapi"，则指向一份 API 文档，渲染成带请求面板的交互参考。导航项支持page、openapi、asyncapi、group、link等多种类型，完整属性说明见 Navigation。

第 3 步：预览、发布与同步

预览部署用于评审改动，正式发布走 CLI，或接入 GitHub Actions 实现自动部署：

npx @scalar/cli project publish

三种部署触发方式各有所长：

• 预览部署：为 Pull Request 生成一条独立链接，供合并前评审，见 Preview Deployments。
• 自动部署：变更合并后自动发布，见 Automatic Deployment。
• GitHub Actions：按事件触发发布，见 GitHub Actions。
• CLI：从终端或任意 CI/CD 环境发布，见 CLI。

内容可以放在哪里

Docs 不强制你只用 Git。下表说明三种内容来源，帮助你按团队习惯选型：

核心配置文件 scalar.config.json

scalar.config.json是 Docs 的中心配置，定义项目元数据、导航结构、站点设置与部署选项。最小可用结构如下（$schema用于在 VS Code/Cursor 中获得自动补全与校验）：

{ "$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 本身就是一份活样本。它把本文所在的 getting-started 页面注册为一条page路由（第 1728-1729 行）：

"getting-started": { "type": "page", "filepath": "documentation/guides/docs/getting-started.md" }

这说明两件事：其一，filepath是相对仓库根目录的路径，而非相对配置文件所在目录；其二，title、description、icon均可选，filepath才是必填的渲染入口。同一份配置里还演示了如何用siteConfig.routing.redirects把旧 URL 批量重定向到新结构（例如把/scalar/scalar-docs/getting-started映射到/products/docs/getting-started），这正是文档站点改版时避免外链失效的关键机制。

为 API 参考选择数据源

navigation.routes里的 API 参考项支持三种取数方式，理解它们能帮你避免部署后"内容为空"的坑：

1. 本地文件：filepath指向仓库内的 API 文档，随仓库一起构建。
2. Registry：用namespace+slug引用已上传的文档，Registry 更新时会重新发布所有引用它的 Docs 项目。
3. 远程 URL：url在构建时被拉取并写入站点，读者打开页面时不会再次请求。注意 URL 必须公网可达（构建发出的是不带鉴权头的裸GET），且文档应自包含——绝对https://的$ref会被跟随并打包，相对$ref则保持原样、依赖它的部分会渲染为空。

本地预览与发布实操

本地预览

scalar project preview

启动后访问http://localhost:7970，实时查看改动。

发布前认证

先登录 Scalar 账号，再执行发布。支持邮箱密码或个人令牌两种方式：

scalar auth login --email your@email.com --password yourpassword scalar auth login --token your-personal-token

用scalar auth whoami可校验当前登录状态。

发布与常用选项

scalar project publish有两种部署模式：

• 默认：把本地磁盘上的配置与内容上传到 Scalar，磁盘里有什么就部署什么。
• --github：仅当项目已连接 GitHub 仓库时使用，Scalar 从远端拉取文件部署，忽略本地改动。适合从关联仓库触发一次部署。

常用参数：

发布成功后，站点将可通过https://your-subdomain.apidocumentation.com访问。

回滚

若某次部署引入了问题，可先列出生产环境的近期部署，再回滚到指定构建：

# 查看近期生产部署 scalar project deployments list --slug your-docs # 回滚到上一个构建（或用 --to <build-id> 指定） scalar project rollback --slug your-docs

用 GitHub Actions 自动发布

在仓库中放一个 workflow，即可在主分支推送时自动发布。基本工作流：

# .github/workflows/publish-scalar-project.yml name: Publish Scalar Project on: push: branches: - main jobs: publish-project: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 with: node-version: 24 - name: Log in to Scalar run: npx @scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish Project run: npx @scalar/cli project publish --slug your-docs

SCALAR_API_KEY需在仓库 Secrets 中配置。若需要按环境区分 slug（如 main 与 development 分支各自发布到不同项目），可在 workflow 里按github.ref分支设置PROJECT_SLUG环境变量，完整示例见 GitHub Actions。

排错与下一步

发布出问题或拿不准配置是否合法时，用这条命令校验scalar.config.json：

npx @scalar/cli project check-config

继续深入的推荐阅读路径：

• 用 Starter Kit 生成一个开箱即用的项目脚手架；
• 用 scalar.config.json 配置站点元数据、主题与 head；
• 用 Navigation 组织侧边栏、页头、标签页与分组；
• 用 GitHub Actions 实现按事件自动部署。

如果你只想要一份 API 参考（而非完整文档站），可直接使用开源且免费的 API Reference，它对多种 REST 框架提供了集成。

【免费下载链接】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