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 initproject 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。下表说明三种内容来源帮助你按团队习惯选型来源说明GitHub内容与 API 文档都留在仓库里。配合 预览部署、自动部署、GitHub Actions 与 scalar.config.json 使用。任意文件夹或 CLI无需授予仓库访问权限直接在任意目录工作用npx scalar/cli project publish发布详见 CLI。网页编辑器直接在 docs.scalar.com 编辑并托管文档无需 Git。核心配置文件 scalar.config.jsonscalar.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 youve read today }, navigation: { routes: { /: { title: Introduction, type: page, filepath: docs/introduction.md } } } }根级属性一览属性类型说明$schemastring用于编辑器自动补全与校验的 JSON Schema URLscalarstring配置版本最新格式使用2.0.0infoobject项目元数据标题、描述navigationobject导航结构页头链接、路由、侧边栏、标签页详见 Navigationversionsobject多版本导航结构版本化文档用它替代navigationsiteConfigobject站点级配置域名、主题、head、logoassetsDirstring资源目录路径相对仓库根结合仓库真实配置看导航如何落地仓库根目录的 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 参考项支持三种取数方式理解它们能帮你避免部署后内容为空的坑本地文件filepath指向仓库内的 API 文档随仓库一起构建。Registry用namespaceslug引用已上传的文档Registry 更新时会重新发布所有引用它的 Docs 项目。远程 URLurl在构建时被拉取并写入站点读者打开页面时不会再次请求。注意 URL 必须公网可达构建发出的是不带鉴权头的裸GET且文档应自包含——绝对https://的$ref会被跟随并打包相对$ref则保持原样、依赖它的部分会渲染为空。本地预览与发布实操本地预览scalar project preview启动后访问http://localhost:7970实时查看改动。发布前认证先登录 Scalar 账号再执行发布。支持邮箱密码或个人令牌两种方式scalar auth login --email youremail.com --password yourpassword scalar auth login --token your-personal-token用scalar auth whoami可校验当前登录状态。发布与常用选项scalar project publish有两种部署模式默认把本地磁盘上的配置与内容上传到 Scalar磁盘里有什么就部署什么。--github仅当项目已连接 GitHub 仓库时使用Scalar 从远端拉取文件部署忽略本地改动。适合从关联仓库触发一次部署。常用参数参数类型必填说明--slugstring否项目 slug 标识--configstring否指向 scalar.config.json 的路径--previewboolean否以预览模式发布不正式上线--githubboolean否从项目关联的 GitHub 仓库发布本地文件被忽略发布成功后站点将可通过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/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 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-docsSCALAR_API_KEY需在仓库 Secrets 中配置。若需要按环境区分 slug如 main 与 development 分支各自发布到不同项目可在 workflow 里按github.ref分支设置PROJECT_SLUG环境变量完整示例见 GitHub Actions。排错与下一步发布出问题或拿不准配置是否合法时用这条命令校验scalar.config.jsonnpx 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考