git-cliff 官网构建指南:基于 Docusaurus 的文档站搭建、本地开发与静态部署

原创2026-09-22 13:04:331,755 阅读
文章标签:CLI开发工具

git-cliff 官网构建指南:基于 Docusaurus 的文档站搭建、本地开发与静态部署

git-cliff 是一个高度可定制的 Changelog 生成器,其官方文档站(位于仓库 website/ 目录)使用 Docusaurus 构建,涵盖项目文档、版本发布博客与首页展示。本文以 website/README.md 为主线,完整讲解从依赖安装、本地热更新开发、静态站点构建,到通过 GitHub Pages 部署的完整流程,并结合仓库中的实际配置(package.json、docusaurus.config.js、Playwright 端到端测试等)深入剖析每个命令背后的工程细节,帮助读者快速上手维护这套文档站点。

站点概览:git-cliff 的文档站技术栈

git-cliff 的官网是一个典型的 Docusaurus 静态站点。根据 website/README.md,该网站使用 Docusaurus(现代静态网站生成器)构建,代码全部位于仓库根目录下的 website/ 目录中。从 website/package.json 可以确认当前站点的技术栈:

  • @docusaurus/core 与 @docusaurus/preset-classic:版本均为 ^3.9.2,即 Docusaurus 3.x 系列(README 中写的是 Docusaurus 2,实际依赖已升级到 3.x,从依赖版本看属于同一代大版本演进);
  • 本地搜索:@easyops-cn/docusaurus-search-local,为文档站提供站内搜索能力;
  • 前端框架:react / react-dom 19.x,配合 prism-react-renderer 实现代码高亮;
  • Node 环境要求:engines.node >= 18.0,包管理器锁定为 yarn@1.22.22(Classic Yarn)。

站点目录结构高度遵循 Docusaurus 约定:docs/ 存放文档(按配置、使用、安装、集成、模板等分类),blog/ 存放版本发布公告(如 git-cliff-2.14.2.md 等),src/ 存放 React 页面与组件,static/ 存放静态资源。文档侧边栏由 website/sidebars.js 定义,采用 autogenerated 模式,直接从 docs 目录结构自动生成侧边栏。

环境准备:Node 与 Yarn

在执行任何命令之前,先确认环境满足 website/package.json 声明的约束:

  • Node.js ≥ 18.0(engines 字段强制声明,低于此版本 Docusaurus 3.x 无法正常运行);
  • Yarn Classic(仓库通过 packageManager 字段锁定为 yarn@1.22.22,建议使用相同或兼容版本以保证依赖锁文件 yarn.lock 可正确解析)。

第一步:安装依赖

进入网站目录并安装全部依赖:

$ cd website
$ yarn

该命令会依据 website/yarn.lock 锁文件安装全部生产依赖与开发依赖。开发依赖中除 Docusaurus 相关类型包外,还包含 @playwright/test(用于端到端测试)、typescript(用于类型检查)与 chalk(用于测试日志着色),详见 website/package.json 的 devDependencies 字段。

第二步:本地开发(热更新预览)

$ yarn start

该命令对应 website/package.json 中的脚本 "start": "docusaurus start",其行为与 README 描述一致:

  • 启动本地开发服务器(默认监听 http://localhost:3000)并自动打开浏览器窗口;
  • 监听 docs/、blog/、src/ 等目录的文件变更,绝大多数修改即时热更新生效,无需重启服务——包括 Markdown 文档内容、React 组件与样式(如 website/src/css/custom.css)。

值得注意的是,文档与博客内容均以 Markdown 编写(如 website/docs/configuration/index.md、website/blog/git-cliff-2.14.0.md),Docusaurus 会自动将其渲染为带侧边栏、导航栏与搜索框的页面,改动文档后刷新浏览器即可看到效果,这是文档站点维护中最常用的开发循环。

第三步:静态构建与产物检查

$ yarn build

该命令对应 "build": "docusaurus build",生成静态内容到 build 目录,之后可交给任意静态托管服务(如 Nginx、GitHub Pages、CDN 等)发布。

构建过程会执行以下关键校验:

  1. 链接完整性检查:在 website/docusaurus.config.js 中 onBrokenLinks 被设置为 "throw",意味着只要文档内存在失效的内部链接,构建就会直接报错失败,从源头杜绝 404;
  2. Markdown 链接告警:markdown.hooks.onBrokenMarkdownLinks 设为 "warn",对无法自动解析的 Markdown 链接给出警告而非中断;
  3. 本地搜索索引生成:搜索插件在构建阶段生成 hashed 索引文件,支持长期缓存;
  4. 静态资源处理:static/ 目录中的 favicon、图片、字体等会被原样复制到产物中(如 website/static/favicon/favicon.ico)。

第四步:部署到 GitHub Pages

README 提供了两种部署方式,对应 website/package.json 中的 "deploy": "docusaurus deploy" 命令。

方式一:使用 SSH 协议推送

$ USE_SSH=true yarn deploy

适用于本机已配置 SSH key 且能免密推送的情况,部署脚本会直接通过 SSH 推送构建产物到 gh-pages 分支。

方式二:使用 HTTPS + GitHub 用户名

$ GIT_USER=<你的 GitHub 用户名> yarn deploy

适用于未配置 SSH 的环境,GIT_USER 环境变量指定用于认证的 GitHub 用户名,配合本机的凭据(如 PAT)完成推送。

两种方式本质相同:构建站点后将静态产物提交并推送到 gh-pages 分支。若托管在 GitHub Pages 上,这是最便捷的发布途径。仓库在 website/docusaurus.config.js 中已预设了 GitHub Pages 部署所需的元信息(organizationName、projectName、url: "https://git-cliff.org"、baseUrl: "/"),直接执行 deploy 即可。

深入仓库:更多实用脚本与配置解读

常用脚本一览

website/package.json 还提供了 README 之外的其他实用脚本,日常维护中经常用到:

脚本 命令 用途
clear docusaurus clear 清空构建缓存(build、.docusaurus 目录),遇到构建异常或缓存失效时可先执行
serve docusaurus serve 在本地以静态服务器方式预览 build 产物,验证生产构建结果
swizzle docusaurus swizzle 对 Docusaurus 内置主题组件进行定制化改造
write-translations docusaurus write-translations 提取翻译资源文件(站内 i18n 目前仅配置英文,见配置中的 i18n.defaultLocale: "en")
write-heading-ids docusaurus write-heading-ids 为 Markdown 标题批量生成锚点 ID
typecheck tsc 对 src/ 下的 TypeScript 代码执行类型检查

其中 typecheck 依赖 website/tsconfig.json,它继承 @docusaurus/tsconfig 并为编辑器提供类型提示(该文件注释明确指出其用途是"更好的编辑器体验",不参与编译)。

站点配置核心:docusaurus.config.js

website/docusaurus.config.js 是整个站点的中枢配置,值得逐项了解:

  • 站点元信息:title: "git-cliff"、tagline: "A highly customizable changelog generator"、favicon 指向 website/static/favicon/favicon.ico;
  • 导航栏:包含 "Documentation"(指向 docs 首页)与 "News"(指向 /blog)两个主菜单项,以及 Sponsor、GitHub、Discord 等右侧外链;
  • 公告栏:顶部 announcementBar 用于展示最新版本发布公告(当前公告指向 v2.14.0 的博客文章),可关闭;
  • 深色模式:colorMode.defaultMode 为 "dark",默认以深色主题呈现;
  • 本地搜索:通过 themes 字段启用 @easyops-cn/docusaurus-search-local;
  • 代码高亮:prism 配置了 light/dark 两套主题(github / dracula),并注册了 bash、diff、json、yaml、toml、rust、markdown 等额外语言——这与 git-cliff 文档大量使用 TOML 配置示例、Rust 集成示例高度匹配。

端到端质量保障:Playwright 爬站测试

仓库为网站质量提供了自动化保障。website/playwright.config.ts 配置了 Playwright 测试,覆盖 Chromium、Firefox、WebKit 三种浏览器内核;测试用例 website/e2e/crawl.spec.ts 实现了一个站点爬虫:从 https://git-cliff.org/ 出发,递归遍历站内全部链接,监听浏览器控制台输出,收集所有 error / warning 级别日志并统计上报,最终断言控制台错误数为 0,否则测试失败。该测试还支持在 CI 环境(process.env.CI)下启用失败重试与单 worker 串行执行。这意味着每次改动文档或页面代码后,都可以通过运行 Playwright 测试验证整站无控制台错误、无失效页面。

常见问题与维护建议

  1. yarn build 因死链失败:onBrokenLinks: "throw" 是刻意设计的严格策略,遇到构建失败请检查报错中提示的链接,修正文档中的相对路径或锚点后重新构建;
  2. 本地改动不生效:先确认 yarn start 进程仍在运行,若改动涉及 docusaurus.config.js 或 sidebars.js 等配置类文件,Docusaurus 通常会自动重启,若未生效可手动重启或执行 yarn clear 清理缓存;
  3. 部署推送失败:SSH 方式请确认本机 SSH key 已添加且可免密推送;非 SSH 方式请确认 GIT_USER 已正确设置且本机有对应仓库的推送凭据;
  4. 新增文档分类:在 website/docs/ 下新建目录与 Markdown 文件即可,侧边栏会自动生成;如需调整排序,可在文档头部 front matter 中设置 sidebar_position 字段;
  5. 发布新版本公告:在 website/blog/ 下新增 git-cliff-<版本>.md 文件,并同步更新 website/docusaurus.config.js 中 announcementBar 的公告链接与文案。

总结

git-cliff 官网的维护链路清晰完整:yarn 安装依赖 → yarn start 本地热更新写作 → yarn build 严格校验并产出静态文件 → USE_SSH=true yarn deploy(或 GIT_USER=... yarn deploy)一键发布到 GitHub Pages 的 gh-pages 分支,再辅以 Playwright 爬站测试做整站质量把关。掌握这套流程后,无论是修正文档笔误、补充新的配置章节,还是发布版本更新公告,都能在几分钟内完成从改稿到上线的完整闭环。

登录后查看全文
git-cliff