git-cliff 官网构建指南:基于 Docusaurus 的文档站搭建、本地开发与静态部署
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-dom19.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 等)发布。
构建过程会执行以下关键校验:
- 链接完整性检查:在 website/docusaurus.config.js 中
onBrokenLinks被设置为"throw",意味着只要文档内存在失效的内部链接,构建就会直接报错失败,从源头杜绝 404; - Markdown 链接告警:
markdown.hooks.onBrokenMarkdownLinks设为"warn",对无法自动解析的 Markdown 链接给出警告而非中断; - 本地搜索索引生成:搜索插件在构建阶段生成
hashed索引文件,支持长期缓存; - 静态资源处理:
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 测试验证整站无控制台错误、无失效页面。
常见问题与维护建议
yarn build因死链失败:onBrokenLinks: "throw"是刻意设计的严格策略,遇到构建失败请检查报错中提示的链接,修正文档中的相对路径或锚点后重新构建;- 本地改动不生效:先确认
yarn start进程仍在运行,若改动涉及docusaurus.config.js或sidebars.js等配置类文件,Docusaurus 通常会自动重启,若未生效可手动重启或执行yarn clear清理缓存; - 部署推送失败:SSH 方式请确认本机 SSH key 已添加且可免密推送;非 SSH 方式请确认
GIT_USER已正确设置且本机有对应仓库的推送凭据; - 新增文档分类:在 website/docs/ 下新建目录与 Markdown 文件即可,侧边栏会自动生成;如需调整排序,可在文档头部
front matter中设置sidebar_position字段; - 发布新版本公告:在 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 爬站测试做整站质量把关。掌握这套流程后,无论是修正文档笔误、补充新的配置章节,还是发布版本更新公告,都能在几分钟内完成从改稿到上线的完整闭环。