Scalar Docs用 Markdown 与 OpenAPI 构建一体化开发者门户的技术指南【免费下载链接】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 Docs 是 Scalar 平台中的产品文档门户把产品指南与交互式 API Reference 放进同一个站点内容用 Markdown 或 MDX 编写可从 GitHub 拉取支持对每个 Pull Request 生成预览部署并在合并时自动发布或任意通过 CLI 部署从而让文档始终与代码保持同步。读完本文你将理解 Scalar Docs 的能力边界Markdown/MDX、自定义主题与域名、GitHub 同步、预览部署、CI/CD 集成掌握scalar.config.json的核心配置结构与 CLI 发布流程并能参照本仓库自身的真实配置快速搭建自己的文档站点。产品定位指南与 API Reference 二合一Scalar Docs 的定位是“产品指南和 API Reference 合并在同一个开发者门户中”。其核心承诺是文档始终基于团队已经在维护的 API 文档即 OpenAPI 标准生成因此文档与 API 保持同步无需额外维护一套独立的 API 文档。对只想要一个独立 API Reference 的场景官方在 Scalar Docs 概览 中明确建议改用开源、免费、并带有 REST API 框架集成能力的 API Reference。二者分工清晰API Reference 负责单个或多个 API 的交互式参考而 Docs 负责把“产品指南 多个 API Reference 自定义内容与主题”整合成一个完整的开发者门户。核心能力清单概览页用一组特性标签总结了 Scalar Docs 的能力面这也是后续配置章节要逐项落实的对象能力说明Markdown MDX指南正文使用 Markdown 或 MDX 编写支持富内容与可编程块Custom HTML/CSS/JS通过自定义脚本、样式与 HTML 片段扩展页面Fast CDN内容经 CDN 分发Multiple API references同一站点挂载单个或多个 API 的交互式参考Custom themes layouts自定义主题、配色与布局Custom domains绑定自定义域名也可用平台子域名Fine-grained access细粒度访问控制私有文档、RBACSync with GitHub从 GitHub 仓库同步内容与 API 文档Ask AI站点内置 AI 问答CI/CD integration与 CI/CD 流水线集成自动化部署这些能力在实现层面几乎都对应scalar.config.json里的某个字段下文会结合本仓库的真实配置逐一印证。本仓库就是 Scalar Docs 的自证案例概览页有一句关键声明“All of scalar.com is fully built with Scalar Docsscalar.com 全站完全由 Scalar Docs 构建”。在当前仓库中这句话可以直接验证仓库根目录下的 scalar.config.json 就是驱动整个 scalar.com 文档站点的中央配置文件仓库documentation/目录下的所有 Markdown 指南、API Reference 与资源页都通过该配置被组织成一个站点。该配置文件的头部即为最小可运行结构字段含义与官方配置参考完全一致{ $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, info: { title: Scalar Documentation, description: Guides for Scalar, covering your favorite frameworks, languages and use cases. }, assetsDir: documentation/assets }对照官方给出的字段参考根级属性如下详见 scalar.config.json 配置参考属性类型说明$schemastring用于编辑器自动补全与校验的 JSON Schema 地址scalarstring配置版本号最新格式使用2.0.0infoobject项目元数据标题、描述navigationobject导航结构头部链接、路由、侧边栏、标签页versionsobject多版本导航结构版本化文档时替代navigationsiteConfigobject站点级配置域名、主题、head、logoassetsDirstring资源目录路径相对仓库根本仓库的配置正体现了“以指南为主体、API Reference 与资源页共存”的结构info.title为Scalar DocumentationassetsDir指向 documentation/assets而站点级的域名、head、footer、重定向全部收敛在siteConfig中。站点级配置域名、head 与自定义资源siteConfig负责把“内容”变成“一个可访问的站点”。官方参考列出的关键字段包括属性类型说明themestring视觉主题如default、alternate、moon、purple、solarized、bluePlanet、deepSpace、saturn、kepler、marslogoobject深色/浅色模式下的 Logo URLheadobject自定义脚本、样式、meta 标签与链接routingobjectURL 重定向配置subpathstring多项目部署时使用的 URL 子路径如/guides、/apicolorSchemeobject亮/暗外观设置layoutobject全局布局选项含搜索配置本仓库的 scalar.config.json 中siteConfig同时设置了subdomainscalar与customDomainscalar.com并在head.scripts/head.styles/head.meta/head.links中挂载了站点脚本、自定义样式、Open Graph 元数据与 favicon。它还为footer指定了独立文件 documentation/footer.html并为rss配置了变更日志 feed。这正对应能力清单中“Custom HTML/CSS/JS”“Custom domains”“Custom themes layouts”三项能力在真实配置中的落点。此外siteConfig.routing.redirects支持把旧路径批量重定向到新路径。本仓库的配置中包含了一条覆盖从/scalar/scalar-docs/...到/products/docs/...的完整迁移映射用于站点改版后保持旧链接可用——这是门户长期运营时维护 SEO 与链接稳定性的典型做法。内容从哪里来GitHub、任意文件夹与 Web 编辑器概览页“从 GitHub 拉取内容”的能力在 Getting Started 中被拆成三种内容来源读者可按团队工作流任选其一来源说明GitHub内容与 API 文档保存在仓库中使用预览部署、自动部署、GitHub Actions 与scalar.config.json任意文件夹 / CLI无需授予仓库访问权限从任意文件夹或仓库工作用npx scalar/cli project publish发布Web 编辑器在平台 Web 编辑器中编辑并保存无需 Git其中“从 GitHub 拉取 合并时自动部署”正是siteConfig中 Git Sync 与重定向能力所服务的场景而“任意文件夹 / CLI”则让没有 Git 工作流或不便授予仓库权限的团队也能直接发布。三步创建并发布文档Getting Started 把发布流程压缩为三步本文按此骨架展开并补充 CLI 细节第一步启动项目。从 Dashboard、Starter Kit或任意包含scalar.config.json的文件夹启动。可先本地预览npx scalar/cli project preview本地预览会在http://localhost:7970启动一个开发服务器每次编辑即时可见见 Starter Kit。第二步添加指南与 API。用 Markdown 或 MDX 编写指南再在scalar.config.json的navigation.routes中挂载路由。最小示例如下{ navigation: { routes: { /getting-started: { type: page, filepath: docs/getting-started.md } } } }若要挂交互式 API Reference则把路由类型改为openapi并指向 OpenAPI 文档的url若要组织为分组则使用type: group加children参见 导航配置。第三步预览、发布与同步。用预览部署做评审用 CLI 发布或接入 GitHub Actions 自动部署npx scalar/cli project publishCLI 发布流程CLI 部署文档 给出可复制运行的完整命令集。scalar project publish支持两种部署方式默认CLI 把本机磁盘上的项目配置与内容上传到平台磁盘上是什么就部署什么。--github仅当项目已连接 GitHub 仓库时使用。Scalar 从 GitHub 拉取文件并部署忽略本地改动用于从远端仓库触发部署。安装与认证npm install -g scalar/cli # 或不安装直接用 npxnpx scalar/cli project publishscalar auth login # 邮箱密码或令牌 scalar auth login --email youremail.com --password yourpassword scalar auth login --token your-personal-token scalar auth whoami # 查看当前认证状态初始化与建项目scalar project init scalar project create --name My Documentation --slug your-docs本地预览、预览部署与正式发布scalar project preview scalar project publish --slug your-docs --preview scalar project publish scalar project publish --slug your-docs --config scalar.config.json scalar project publish --githubproject publish的常用选项如下选项类型必填说明--slugstring否项目 slug 标识--configstring否scalar.config.json文件路径--previewboolean否以预览模式发布不上线--githubboolean否从项目关联的 GitHub 仓库发布忽略本地文件发布完成后站点将可通过https://your-subdomain.apidocumentation.com访问。若发布出问题可用scalar project deployments list --slug your-docs查看历史构建并用scalar project rollback --slug your-docs或--to build-id回滚到之前的构建。此外Starter Kit 提供了npx scalar/cli project check-config用于校验scalar.config.json是否合法是排查“站点没起来”的首选手段。预览部署与自动化流水线“对每个 PR 生成预览”的能力由 Preview Deployments 支撑开启后每个 Pull Request 会自动创建预览部署并可在 PR 中回贴一条带预览直链的评论让评审者在合并前直接查看文档效果。未连接 GitHub 的项目则可用npx scalar/cli project publish --slug your-docs --preview手动触发预览。自动化方面GitHub Actions 给出了可复制的 workflow在push到main时 checkout 仓库、设置 Node.js、用令牌登录 Scalar、再执行npx scalar/cli project publish --slug your-docs。文档还给出了基于分支的环境化部署示例main映射到生产 slugdevelopment映射到开发 slug实现“合并即发布、按环境分流”。这与概览页“deploy on merge or from anywhere with the CLI”的承诺一致。版本与订阅能力分层概览页给出了 Docs 的能力分层表用于判断哪些功能在免费层可用、哪些需要更高订阅详细对比见 定价说明能力FreeProEnterprise子域名、API Reference、主题、邮箱域名访问包含包含包含自定义域名、指南、版本、Git Sync、Markdown、MDX、落地页无包含包含SSO/SAML、RBAC、优先支持、专属 Slack 或 Teams 支持无无包含从这张表可以看出能力分层的技术含义免费层即可获得子域名托管、交互式 API Reference 与主题定制而把内容纳入 Git 工作流Git Sync、使用 Markdown/MDX、多版本、自定义域名与落地页等“生产级”能力在 Pro 层SSO/SAML、RBAC 等访问与合规能力则位于 Enterprise 层。小结Scalar Docs 把“产品指南 多个 API Reference 自定义内容与主题”统一到一份 scalar.config.json 之下内容用 Markdown/MDX 编写API Reference 基于 OpenAPI 保持同步部署可通过 GitHub 自动同步、CLI 或 CI/CD 触发并支持预览部署、回滚与自定义域名。本仓库以documentation/目录下的全部指南和根目录的中央配置文件作为“整个 scalar.com 由 Scalar Docs 构建”的可验证实例读者可据此对照 配置参考 与 CLI 文档 搭建自己的文档门户。【免费下载链接】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），仅供参考