asdf 文档站点贡献指南：基于 VitePress 构建多语言技术文档

asdf 文档站点贡献指南基于 VitePress 构建多语言技术文档【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文面向希望为 asdf 项目文档站点贡献内容的开发者完整介绍本地文档开发环境的搭建流程、VitePress 静态站点的配置结构、按 locale 拆分的国际化组织方式以及符合自动化发布流水线要求的docs类型 PR 提交规范。读完本文你将能够独立搭建文档站开发环境、理解站点配置的每一层含义并提交一条可被 CI 与发布工具正确识别的文档改动。环境准备克隆仓库并用 asdf 管理文档工具链asdf 的文档站点与其核心代码存放在同一仓库中文档目录位于 docs/ 下。开始贡献的第一步是 Fork 仓库并克隆默认分支# 克隆你自己的 fork git clone 你的 fork 地址 # 或直接克隆 asdf 仓库 git clone https://gitcode.com/GitHub_Trending/as/asdf与核心开发类似文档站点的开发工具同样由 asdf 自身来管理。核心开发所用的工具版本记录在仓库根目录的 .tool-versions包含 bats、shellcheck、shfmt、golang而文档站点专属的工具版本则记录在 docs/.tool-versions 中当前内容为nodejs 22.10.0也就是说文档开发只需要 Node.js 这一个运行时。如果你本机已安装 asdf可以添加 nodejs 官方插件后一键安装对应版本# 添加 asdf-nodejs 插件 asdf plugin add nodejs # 读取 docs/.tool-versions 并安装指定版本 asdf installasdf install会依据当前目录层级中的.tool-versions自动安装相应工具版本——在docs/目录下执行即为 Node.js 22.10.0。之后在 docs/package.json 所在目录安装 JavaScript 依赖npm install依赖清单同样记录在 docs/package.json 中其devDependencies仅包含两项types/node: ^26.1.2, prettier: ^3.9.6, vitepress: ^1.6.4整个文档站只依赖 VitePress 这一构建核心与 Prettier 这一格式化工具配置极简。技术选型为什么文档站选择了 VitePress文档站点使用 VitePress 作为静态站点生成器SSG。这一选择并非一蹴而就而是经历了两次替换最初使用 Docsify.js随后换到 VuePress最终定位于 VitePress。替换的核心动因是一个明确的工程诉求——在用户未启用或无法使用 JavaScript 时站点必须能提供纯 HTML 的降级渲染。Docsify 无法满足这一要求而 VitePress 很快取代了 VuePress 成为默认选项。除渲染能力外VitePress 的功能集与此前方案大体一致核心思路是以 Markdown 文件为主、几乎零配置即可组织站点内容。从仓库实际状态看docs/ 目录下的所有页面guide、manage、plugins、contribute、more 等章节均为纯 Markdown 文件而首页 docs/index.md 则通过 frontmatter 声明为layout: home配合hero与features两个配置块渲染出项目首页的横幅与特性卡片。需要说明的是原贡献文档写作时标注为 VitePress (v2)而当前仓库 docs/package.json 中实际锁定的版本为vitepress ^1.6.4具体行为以仓库当前锁定版本为准。开发工作流scripts、本地服务器与格式化站点开发相关的全部脚本定义在 docs/package.json 的scripts字段中scripts: { fmt: prettier --write .vitepress/{config,navbars,sidebars}.ts .vitepress/theme/**/*, dev: vitepress dev, build: vitepress build, preview: vitepress preview }npm run dev启动本地开发服务器支持热更新是日常编写文档时的主要入口npm run build构建生产环境的静态站点npm run preview本地预览生产构建产物npm run fmt使用 Prettier 格式化站点配置文件与主题代码。注意其格式化范围刻意限定在.vitepress目录内的config.ts、navbars.ts、sidebars.ts与theme/子目录Markdown 正文不在此列。提交前应运行格式化保持配置文件风格统一npm run fmtPR 与提交规范使用 docs 类型的 Conventional Commitsasdf 使用自动化发布流水线发布版本号与 Changelog 的生成都依赖PR 标题中的 Conventional Commits约定式提交规范。该规范的完整说明位于 docs/contribute/core.md核心约定如下type[optional scope][optional !]: description !-- 示例 -- fix: some fix feat: a new feature docs: some documentation update docs(website): some change for the website feat!: feature with breaking changetype的完整集合为feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。其中fix对应 SemVer 的patch版本递增feat对应minor版本递增任意 type 后追加!表示破坏性变更对应major版本递增。针对文档改动PR 标题必须使用docs类型格式为docs: description。这是自动化流水线识别本次变更仅涉及文档、不应触发核心版本号提升的关键信号。若改动的是站点本身如导航、侧边栏或主题可使用带 scope 的形式例如docs(website): some change for the website。站点配置解剖config / navbars / sidebars 三文件拆分站点配置全部集中在 docs/.vitepress/ 目录下由三个 TypeScript 文件协作完成原贡献文档写作时描述为.js当前仓库实际为.tsdocs/.vitepress/config.ts站点根配置调用 VitePress 的defineConfig声明站点的title、description、lastUpdated、locales以及全局themeConfig含search: { provider: local }本地全文搜索与 GitHub 社交链接docs/.vitepress/navbars.ts导航栏配置按 locale 拆分导出docs/.vitepress/sidebars.ts侧边栏配置同样按 locale 组织内容覆盖 Guide、Usage、Reference、Plugins、Contribute 等完整章节。将导航栏与侧边栏这两个体积较大的配置对象从根配置中抽离、按 locale 单独维护是为了让 docs/.vitepress/config.ts 保持精简——实际根配置仅约 60 行主要职责是组装各 locale 的导航与侧边栏引用。导航栏配置中还有一个值得留意的实现细节getVersion()会尝试从仓库根目录的.release-please-manifest.json读取当前发布版本号并渲染进导航栏该文件由 Release Please 自动化发布流水线维护。这意味着导航栏上的版本号是动态生成的无需手工更新也与自动化发布的工程理念保持一致。国际化 i18nlocales 配置与目录结构约定VitePress 对国际化i18n提供一等支持。站点支持哪些语言完全由根配置中的locales对象决定。当前仓库 docs/.vitepress/config.ts 中定义了 5 个 localelocales: { root: { label: English, lang: en-US, themeConfig: { nav: navbars.en, sidebar: sidebars.en, }, }, ko-kr: { label: 한국어, lang: ko-kr, themeConfig: { nav: navbars.ko_kr, sidebar: sidebars.ko_kr, }, }, ja-jp: { label: 日本語, lang: ja-jp, themeConfig: { nav: navbars.ja_jp, sidebar: sidebars.ja_jp, }, }, pt-br: { label: Brazilian Portuguese, lang: pr-br, themeConfig: { nav: navbars.pt_br, sidebar: sidebars.pt_br, }, }, zh-hans: { label: 简体中文, lang: zh-hans, themeConfig: { nav: navbars.zh_hans, sidebar: sidebars.zh_hans, }, }, },每个 locale 都包含三部分信息语言选择下拉菜单中显示的名称label、页面lang属性、以及指向 docs/.vitepress/navbars.ts 与 docs/.vitepress/sidebars.ts 中对应导出对象的引用。目录结构的硬性约定每个 locale 的 Markdown 内容必须放在与locales键同名的文件夹下且需要与英文内容保持相同的文件树结构。原贡献文档以pt-BR为例给出了规范化的目录镜像docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ pt-BR ├─ README.md ├─ foo.md └─ nested └─ README.md即若英文侧存在foo.md与nested/README.md翻译侧必须存在同路径的pt-BR/foo.md与pt-BR/nested/README.md否则对应页面将缺失或 404。从当前仓库状态看这一约定已落地为四个翻译目录docs/ja-jp/、docs/ko-kr/、docs/pt-br/、docs/zh-hans/且每个目录均完整镜像了英文侧的contribute/、guide/、manage/、more/、plugins/结构例如 docs/zh-hans/contribute/documentation.md 与 docs/zh-hans/manage/configuration.md。对于新增语言需要同时完成三件事在locales中登记新条目含 label、lang 与导航/侧边栏引用、在 docs/.vitepress/navbars.ts 与 docs/.vitepress/sidebars.ts 中新增对应语言的对象并导出、然后在docs/下创建与 locale 键同名的目录镜像英文文档树。小结asdf 的文档站点是一个典型的工具链自举工程用 asdf 本身管理文档开发所需的 Node.js 版本用 VitePress 的 Markdown 优先哲学承载全部内容用约定式提交把文档改动无缝接入自动化发布流水线再用 locales 机制支撑英、日、韩、葡、中五种语言的内容同步维护。理解 docs/.vitepress/ 下三份配置文件的拆分逻辑与 locale 目录镜像约定是提交高质量文档贡献的前提而牢记docs: description的 PR 标题格式则是让你的改动顺利通过 CI 并进入发布流程的最后一公里。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考