★ FEATURED ARTICLE CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本篇指南介绍如何在 Woodpecker 开源仓库中参与官方文档的编写与维护。Woodpecker 的文档站基于 Docusaurus 构建本文将从改一行文本到在本地完整运行文档站给出可复现的操作流程并结合仓库内的docs/package.json、docusaurus.config.ts与Makefile等源码细节说明热重载、静态构建、版本化管理与 CI 集成背后的实现原理。读完本文你将能够熟练地修改 Woodpecker 文档、在本地预览渲染效果并理解文档发布链路。文档站的技术栈与目录结构Woodpecker 官方文档使用Docusaurus作为站点框架见 docs/package.json 中docusaurus/core、docusaurus/preset-classic依赖Docusaurus 是一个基于 React 的现代静态站点生成器支持 Markdown 写作、多版本文档、代码高亮、全文搜索与 OpenAPI 集成。它的官方文档中提供了完整的框架学习资料建议在动手前先熟悉其基本概念。仓库中与文档站相关的目录和文件主要包括docs/docs/当前版本Next的 Markdown 源码日常新增、修改文档的主要位置docs/versioned_docs/已发布版本的文档快照例如docs/versioned_docs/version-3.16/对应 3.16 版本本指南即位于docs/versioned_docs/version-3.16/92-development/04-docs.mddocs/versioned_sidebars/各历史版本的侧边栏配置快照docs/plugins/woodpecker-plugins/文档站使用的自定义 Docusaurus 主题/插件源码TypeScript用于渲染插件列表等页面docs/docusaurus.config.ts站点全局配置导航、主题、版本策略、插件等docs/sidebars.js当前版本文档的侧边栏结构docs/static/静态资源图片、favicon、SVG 等docs/package.json与docs/pnpm-lock.yaml文档站的依赖声明与锁定文件使用pnpm管理。快速上手本地预览与构建前置条件安装 Node.js 与 pnpm与开发 Woodpecker 前端 UI 一样构建文档站需要 Node.js 与pnpm。详见 开发环境准备安装 Node.js 与 pnpm当前版本对应 docs/docs/92-development/01-getting-started.md先安装 Node.js再按 pnpm 官方安装指引安装pnpm文档站的依赖一律通过pnpm安装。安装依赖并构建文档插件进入docs/目录后先安装依赖再构建文档站依赖的自定义插件cd docs/ pnpm install # build plugins used by the docs pnpm build:woodpecker-plugins其中pnpm build:woodpecker-plugins会进入docs/plugins/woodpecker-plugins子目录执行pnpm i pnpm build见 docs/package.json把 TypeScript 编写的插件主题编译到dist/Docusaurus 在启动时会加载它docusaurus.config.ts中通过themes字段引用该dist目录。首次本地运行前必须先执行这一步否则站点可能缺少自定义主题产物。启动本地开发服务器热重载pnpm start该命令会启动 Docusaurus 本地开发服务器。文档站支持热重载修改 Markdown 后浏览器中的页面会自动刷新无需手动重启或刷新非常适合边改边看。从源码细节看pnpm start实际执行的是cd ../ make generate-docs cd docs docusaurus start见 docs/package.json。也就是说启动前会自动触发一次make generate-docs其作用是生成两份动态文档见 Makefilegenerate-docs: ## Generate docs (currently only for the cli) CGO_ENABLED0 go generate cmd/cli/app.go CGO_ENABLED0 go generate cmd/server/openapi.gogo generate cmd/cli/app.go从 CLI 命令定义生成命令行参考文档go generate cmd/server/openapi.go生成 OpenAPI JSON供/api/页面的 Redoc 渲染使用见docusaurus.config.ts中的redocusauruspreset。因此本地预览到的文档中CLI 参考与 API 文档始终与当前代码保持同步。构建静态站点pnpm build该命令先把文档构建为纯静态站点产物输出到docs/build/目录可部署到任意静态页面托管服务。与start不同build会先执行pnpm build:woodpecker-plugins再执行docusaurus build见 docs/package.json。按修改场景选择工作流根据改动规模文档站提供两种不同的工作流场景一只修改文字内容如果只是调整某个页面的措辞、修正笔误或补充段落直接在docs/docs/目录下找到对应的 Markdown 文件修改即可无需启动本地服务器。例如想修改入门页直接编辑docs/docs/92-development/01-getting-started.md。Woodpecker 文档遵循标准的 Markdown 基本语法纯文本修改通常不会引入渲染问题。场景二较大改动或需要验证渲染效果当涉及结构调整、新增页面、修改导航、改动代码块或希望预览最终渲染效果时建议在本地完整运行 Docusaurus即上一节的完整命令序列借助热重载即时查看效果最后用pnpm build验证生产构建是否通过。源码级细节站点配置与版本管理docs/docusaurus.config.ts是理解文档站行为的关键其中几个与文档写作直接相关的配置值得注意严格链接检查onBrokenLinks: throw、onBrokenAnchors: throw、onBrokenMarkdownLinks: throw、onBrokenMarkdownImages: throw见 docusaurus.config.ts 与 L319-L325。构建时任何失效的文档内链接、锚点或图片都会直接导致构建失败。这意味着你在文档中新增的相对链接必须指向真实存在的文件也正因如此历史版本快照中的文档链接需要保持与当时目录结构一致多版本机制docsVersions中current版本标记为Next 旧版本按versions.json顺序生成非最新历史版本会加上unmaintained横幅见 docusaurus.config.ts。includeVersions决定了站内实际包含哪些版本目录onlyIncludeVersions与lastVersion配合控制默认展示版本本地全文搜索通过easyops-cn/docusaurus-search-local主题提供站内搜索docusaurus.config.ts因此本地构建即具备搜索能力OpenAPI 文档redocusauruspreset 加载openapi.json在/api/路由渲染 REST API 参考docusaurus.config.ts代码高亮prism主题配置了json、bash、yaml、ini、diff、nix等附加语言docusaurus.config.ts撰写配置类文档时可放心使用这些语言的代码块。docs/sidebars.js定义当前版本文档的导航结构历史版本则使用docs/versioned_sidebars/下的快照。新增一篇文档时若希望它出现在侧边栏需要同步调整侧边栏配置而不是只添加 Markdown 文件。与 Makefile / CI 的集成文档构建已纳入仓库的 Makefile 与 CI 流水线make docs-dependencies在docs/下执行pnpm install --frozen-lockfile见 Makefile锁定依赖以保证可复现构建make generate-docs生成 CLI 与 OpenAPI 文档见上文make build-docs串联generate-docs与docs-dependencies后执行pnpm buildMakefileCI 中部署站点前即运行该目标拼写检查Makefile中的lint流程会对docs/docs/排除versioned_docs执行cspell拼写检查见 Makefile因此新增文档应避免拼写错误专有名词可酌情加入词典。部署方面docs/README.md说明站点最终通过 CI 部署到 Woodpecker 官方文档站。如果你需要本地预览生产形态的站点pnpm build之后可用pnpm serve在本地提供静态预览若需清空构建缓存可执行pnpm clear如需生成或校验翻译占位可执行pnpm write-translations相关脚本均定义在 docs/package.json。写作实践建议结合 Docusaurus 的严格校验机制与 Woodpecker 文档站的工程实践参与文档维护时建议遵循以下约定定位准确当前版本的文档一律写在docs/docs/下历史版本快照docs/versioned_docs/version-*/仅在版本发布时由 Docusaurus 生成不要手工在快照目录里堆积未经发布流程的内容链接规范文档内引用其他页面时使用相对于该文档所在目录的相对路径如../10-intro.md确保onBrokenLinks校验能够通过同时注意锚点大小写与标题保持一致保持代码块可复制涉及命令行或配置示例时标注语言并给出真实可执行的完整命令参考 docs/docs/92-development/01-getting-started.md 中.env配置示例的写法提交前自检运行pnpm build确认无断裂链接与图片再运行make lint确认拼写检查通过避免在 CI 阶段返工。综上Woodpecker 的文档站是一个典型的Markdown 写作 Docusaurus 渲染 CI 自动发布工程小改动可以直接编辑 Markdown大改动则通过pnpm start热重载实时预览最终由pnpm build与make build-docs产出可部署的静态站点。掌握这套流程后无论是修正文档还是编写完整的功能指南你都能在本地获得与官方站点一致的渲染结果。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐5分钟掌握Illustrator脚本设计师效率提升终极指南5分钟掌握Illustrator脚本设计师效率提升终极指南 你是否还在为Illustrator中的重复性操作而烦恼是否曾经花费数小时手动调整几十个相似元素文档教程智能硬件具身智能Woodpecker 文档开发实战指南基于 Docusaurus 的本地编辑、构建与多版本维护Woodpecker 文档开发实战指南基于 Docusaurus 的本地编辑、构建与多版本维护 本篇指南面向希望参与 Woodpecker 项目文档维护与开发CI/CDDevOpsLangChainGo 文档站开发指南基于 Docusaurus 的构建、本地预览与自动化部署LangChainGo 文档站开发指南基于 Docusaurus 的构建、本地预览与自动化部署 本文围绕 langchaingo 仓库中的文档站点 docs人工智能大模型AI AgentRAG后端上一篇如何永久保存微信聊天记录终极完整备份指南下一篇Rudeness高级技巧动态计算与实时预览的完美结合创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
