asdf 文档站点贡献指南VitePress 多语言文档站的构建与国际化实践【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文围绕 asdf 项目的官方文档站点docs/目录展开讲解如何为文档站点搭建本地开发环境、理解其基于 VitePress 的工程结构与配置体系并遵循 Conventional Commits 规范提交文档 PR。读完本文你将掌握 asdf 文档站从克隆仓库 → 安装依赖 → 本地预览 → 编写多语言内容 → 提交 PR的完整贡献流程以及站点导航、侧边栏与 i18n 配置的组织方式。初始环境搭建用 asdf 自己管理文档站工具链asdf 项目有一个自举的传统文档站开发所需的工具链同样通过asdf自身来管理版本约束记录在 docs/.tool-versions 文件中。当前仓库中该文件的内容为nodejs 22.10.0也就是说文档站依赖 Node.js 22.10.0且该版本号随仓库提交保证了所有贡献者使用一致的运行环境。第一步获取仓库副本首先在 GitHub 上 forkasdf仓库并克隆默认分支或者直接克隆官方仓库# clone your fork git clone https://github.com/GITHUB_USER/asdf.git # or clone asdf git clone https://github.com/asdf-vm/asdf.git第二步用 asdf 安装 Node.js在仓库根目录下为 Node.js 添加官方维护的 asdf 插件第一方插件与文档站主题直接相关asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs随后根据docs/.tool-versions中的声明安装对应版本asdf installasdf install会读取当前目录向上查找的.tool-versions文件并安装其中声明的所有工具版本由于仓库根目录的.tool-versions与docs/下的声明不同进入docs/目录或在其子目录执行上述命令即可命中docs/.tool-versions。这样既验证了 asdf 本身的可用性也顺便演示了 asdf 管理运行时版本的核心工作流更系统的用法见 docs/guide/getting-started.md。Node.js基于 Chrome V8 JavaScript 引擎构建的 JavaScript 运行时是 VitePress 文档站构建与预览的基础。第三步安装 Node.js 依赖docs/package.json声明了文档站的所有 npm 依赖进入docs/目录后执行npm install开发基于 VitePress 的静态站点asdf 文档站使用 VitePress 作为静态站点生成器SSG。选择它的关键原因是当用户禁用或未启用 JavaScript 时站点仍能提供纯 HTML 回退HTML-only fallback这一点是此前基于 Docsify.js 的方案无法做到的随后 VitePress 又迅速替代了 VuePress成为最终方案。除此之外其特性集与同类工具大体一致核心工作模式就是以极简配置编写 Markdown 文件。需要说明的是原贡献文档中提及 VitePress v2而以当前仓库 docs/package.json 为准实际锁定的开发依赖为vitepress: ^1.6.4另有prettier: ^3.9.6用于格式化、types/node: ^26.1.2提供 Node 类型并声明type: module使用 ESM 模块体系。撰写文档时应以当前仓库的实际依赖版本为准。npm scripts一站式的开发命令docs/package.json中的scripts字段定义了开发所需的全部命令{ type: module, scripts: { fmt: prettier --write .vitepress/{config,navbars,sidebars}.ts .vitepress/theme/**/*, dev: vitepress dev, build: vitepress build, preview: vitepress preview } }其中与文档贡献者直接相关的两条启动本地开发服务器支持热更新边写边看效果npm run dev提交前统一格式化代码作用于.vitepress/下的配置与主题源文件npm run fmt此外npm run build用于产出静态站点输出目录为docs/.vitepress/dist见 docs/.gitignorenpm run preview用于本地预览构建产物。写文档时一般用不到这两条但 CI 构建和本地验证时必不可少。提交流程Pull Request、发布与 Conventional Commitsasdf 使用自动化的发布流水线它依赖 PR 标题中的 Conventional Commits约定式提交格式来判断版本号与生成变更日志。这一机制的详细说明见 docs/contribute/core.md韩文版见 docs/ko-kr/contribute/core.md。为文档更新创建 PR 时请使用约定式提交中的docs类型PR 标题格式为docs: description示例docs: update getting-started guide。标题一旦被合并进默认分支就会成为该提交的提交信息供自动化发布工具Release Please其配置见仓库根目录的 release-please-config.json解析。值得注意的是docs类型不会触发 SemVer 版本号的 patch/minor/major 变更因此文档 PR 是安全的、不影响发版的改动。VitePress 站点配置config / navbar / sidebar 三件套站点配置由若干 TypeScript 文件承载通过 JavaScript 对象来表示配置。核心文件有三个docs/.vitepress/config.ts站点根配置文件定义站点标题、描述、locales 及主题配置docs/.vitepress/navbars.ts按语言导出的顶部导航栏navbar配置对象docs/.vitepress/sidebars.ts按语言导出的侧边栏sidebar配置对象。之所以把导航栏和侧边栏从根配置中拆出来是为了让config.ts保持精简导航栏和侧边栏的体积很大且需要按语言分别维护拆分后各文件职责单一易于 diff 与审阅。从源码看导航栏的版本号注入一个值得关注的实现细节navbars.ts中定义了一个getVersion()函数见 docs/.vitepress/navbars.ts它读取仓库根目录的.release-please-manifest.json解析出以.为 key 的当前版本号并注入导航栏。也就是说导航栏上显示的版本号不是写死的而是随 Release Please 的版本清单自动同步的——这解释了为什么导航栏配置要使用 TypeScript 而非静态 JSON它需要 Node 的fs/path模块做运行时读取。每个语言的导航栏对象结构一致例如英文导航栏包含 Guide、Reference 两个主项以及一个以getVersion()为标题的下拉菜单内含 Changelog 与 Contribute 链接const en [ { text: Guide, link: /guide/getting-started }, { text: Reference, link: /manage/configuration }, { text: getVersion(), items: [ { text: Changelog, link: ... }, { text: Contribute, link: /contribute/core }, ]}, ];侧边栏的目录化组织sidebars.ts同样按语言组织en / ja_jp / ko_kr / pt_br / zh_hans 五份导出每份内部再按 Guide入门→ Usage用法→ Reference参考→ Plugins插件 的逻辑分组条目通过link指向以/开头的虚拟路由路径如/manage/configurationVitePress 会将这些路径解析为docs/下对应的 Markdown 文件。需要新增文档页面时除了放置 Markdown 文件还应在对应的 sidebar 分组中登记链接否则页面不会出现在导航中。I18n多语言站点的国际化机制VitePress 对国际化i18n提供了一等支持。根配置docs/.vitepress/config.ts通过locales字段定义站点支持的所有语言包括在下拉菜单中显示的语言标签label、语言代码lang以及对应的导航栏/侧边栏配置引用。以当前仓库的真实配置为例docs/.vitepress/config.ts的locales部分asdf 文档站共维护五种语言export default defineConfig({ title: asdf, description: Manage multiple runtime versions with a single CLI tool, lastUpdated: true, locales: { 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 }, }, }, themeConfig: { search: { provider: local }, socialLinks: [{ icon: github, link: https://github.com/asdf-vm/asdf }], }, });其中root即英文默认语言其余四种为翻译语言。pt-br的lang字段写作pr-br原文如此为仓库现状新增语言时需要同时保证lang、label与导航栏/侧边栏导出一致。目录结构约定语言文件夹与 locales 键一一对应每种语言的 Markdown 内容必须存放在与locales键同名的文件夹中。也就是说ko-kr的文档位于docs/ko-kr/ja-jp位于docs/ja-jp/pt-br位于docs/pt-br/zh-hans位于docs/zh-hans/而英文文档直接位于docs/根目录下对应root键。参照当前仓库 docs/ 的实际布局其结构与约定如下docs ├─ index.md # 英文首页root locale ├─ guide/ │ ├─ getting-started.md │ └─ introduction.md ├─ manage/ │ ├─ commands.md │ ├─ configuration.md │ ├─ core.md │ ├─ dependencies.md │ ├─ plugins.md │ └─ versions.md ├─ contribute/ │ ├─ core.md │ ├─ documentation.md │ └─ ... ├─ ko-kr/ # ko-kr locale镜像英文目录结构 │ ├─ index.md │ ├─ guide/ │ ├─ manage/ │ ├─ contribute/ │ └─ ... ├─ ja-jp/ ├─ pt-br/ └─ zh-hans/值得注意的是各语言目录并非总是与英文保持完全同步从当前仓库看ja-jp、ko-kr还额外维护了guide/parts/、parts/等共享片段目录如 docs/parts/install-dependencies.md 与各语言的对应副本用于在多个页面间复用安装依赖的说明段落。贡献者新增翻译时应当先核对英文侧是否已存在对应页面再决定是新增翻译还是同步更新。新增一门语言例如法文fr-fr时的标准操作是在docs/.vitepress/navbars.ts与sidebars.ts中新增并导出fr_fr配置在docs/.vitepress/config.ts的locales中新增fr-fr键并引用上述配置新建docs/fr-fr/目录镜像英文目录结构逐页翻译本地通过npm run dev验证提交 PR 时使用docs:前缀标题。VitePress 的 i18n 还支持更细粒度的配置如title、description的语言覆盖但对文档贡献者而言掌握上述目录镜像 locales 键对齐的约定即可完成绝大多数工作。小结为 asdf 文档站点做贡献的完整链路可以概括为四步用 asdf 安装docs/.tool-versions声明的 Node.js → 在docs/下npm install→npm run dev本地编写 Markdown → 以docs: description格式的 PR 标题提交。理解 docs/.vitepress/config.ts、navbars.ts 与 sidebars.ts 三者根配置 按语言拆分的组织方式以及locales键与语言目录的一一对应关系就能在多语言站点中游刃有余地新增、修正与翻译文档。这不仅是一份文档站操作手册也是 asdf 生态用自己管理自己理念在工程实践中的一次完整展示。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 asdf 文档站点贡献指南：VitePress 多语言文档站的构建与国际化实践
asdf 文档站点贡献指南VitePress 多语言文档站的构建与国际化实践【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文围绕 asdf 项目的官方文档站点docs/目录展开讲解如何为文档站点搭建本地开发环境、理解其基于 VitePress 的工程结构与配置体系并遵循 Conventional Commits 规范提交文档 PR。读完本文你将掌握 asdf 文档站从克隆仓库 → 安装依赖 → 本地预览 → 编写多语言内容 → 提交 PR的完整贡献流程以及站点导航、侧边栏与 i18n 配置的组织方式。初始环境搭建用 asdf 自己管理文档站工具链asdf 项目有一个自举的传统文档站开发所需的工具链同样通过asdf自身来管理版本约束记录在 docs/.tool-versions 文件中。当前仓库中该文件的内容为nodejs 22.10.0也就是说文档站依赖 Node.js 22.10.0且该版本号随仓库提交保证了所有贡献者使用一致的运行环境。第一步获取仓库副本首先在 GitHub 上 forkasdf仓库并克隆默认分支或者直接克隆官方仓库# clone your fork git clone https://github.com/GITHUB_USER/asdf.git # or clone asdf git clone https://github.com/asdf-vm/asdf.git第二步用 asdf 安装 Node.js在仓库根目录下为 Node.js 添加官方维护的 asdf 插件第一方插件与文档站主题直接相关asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs随后根据docs/.tool-versions中的声明安装对应版本asdf installasdf install会读取当前目录向上查找的.tool-versions文件并安装其中声明的所有工具版本由于仓库根目录的.tool-versions与docs/下的声明不同进入docs/目录或在其子目录执行上述命令即可命中docs/.tool-versions。这样既验证了 asdf 本身的可用性也顺便演示了 asdf 管理运行时版本的核心工作流更系统的用法见 docs/guide/getting-started.md。Node.js基于 Chrome V8 JavaScript 引擎构建的 JavaScript 运行时是 VitePress 文档站构建与预览的基础。第三步安装 Node.js 依赖docs/package.json声明了文档站的所有 npm 依赖进入docs/目录后执行npm install开发基于 VitePress 的静态站点asdf 文档站使用 VitePress 作为静态站点生成器SSG。选择它的关键原因是当用户禁用或未启用 JavaScript 时站点仍能提供纯 HTML 回退HTML-only fallback这一点是此前基于 Docsify.js 的方案无法做到的随后 VitePress 又迅速替代了 VuePress成为最终方案。除此之外其特性集与同类工具大体一致核心工作模式就是以极简配置编写 Markdown 文件。需要说明的是原贡献文档中提及 VitePress v2而以当前仓库 docs/package.json 为准实际锁定的开发依赖为vitepress: ^1.6.4另有prettier: ^3.9.6用于格式化、types/node: ^26.1.2提供 Node 类型并声明type: module使用 ESM 模块体系。撰写文档时应以当前仓库的实际依赖版本为准。npm scripts一站式的开发命令docs/package.json中的scripts字段定义了开发所需的全部命令{ type: module, scripts: { fmt: prettier --write .vitepress/{config,navbars,sidebars}.ts .vitepress/theme/**/*, dev: vitepress dev, build: vitepress build, preview: vitepress preview } }其中与文档贡献者直接相关的两条启动本地开发服务器支持热更新边写边看效果npm run dev提交前统一格式化代码作用于.vitepress/下的配置与主题源文件npm run fmt此外npm run build用于产出静态站点输出目录为docs/.vitepress/dist见 docs/.gitignorenpm run preview用于本地预览构建产物。写文档时一般用不到这两条但 CI 构建和本地验证时必不可少。提交流程Pull Request、发布与 Conventional Commitsasdf 使用自动化的发布流水线它依赖 PR 标题中的 Conventional Commits约定式提交格式来判断版本号与生成变更日志。这一机制的详细说明见 docs/contribute/core.md韩文版见 docs/ko-kr/contribute/core.md。为文档更新创建 PR 时请使用约定式提交中的docs类型PR 标题格式为docs: description示例docs: update getting-started guide。标题一旦被合并进默认分支就会成为该提交的提交信息供自动化发布工具Release Please其配置见仓库根目录的 release-please-config.json解析。值得注意的是docs类型不会触发 SemVer 版本号的 patch/minor/major 变更因此文档 PR 是安全的、不影响发版的改动。VitePress 站点配置config / navbar / sidebar 三件套站点配置由若干 TypeScript 文件承载通过 JavaScript 对象来表示配置。核心文件有三个docs/.vitepress/config.ts站点根配置文件定义站点标题、描述、locales 及主题配置docs/.vitepress/navbars.ts按语言导出的顶部导航栏navbar配置对象docs/.vitepress/sidebars.ts按语言导出的侧边栏sidebar配置对象。之所以把导航栏和侧边栏从根配置中拆出来是为了让config.ts保持精简导航栏和侧边栏的体积很大且需要按语言分别维护拆分后各文件职责单一易于 diff 与审阅。从源码看导航栏的版本号注入一个值得关注的实现细节navbars.ts中定义了一个getVersion()函数见 docs/.vitepress/navbars.ts它读取仓库根目录的.release-please-manifest.json解析出以.为 key 的当前版本号并注入导航栏。也就是说导航栏上显示的版本号不是写死的而是随 Release Please 的版本清单自动同步的——这解释了为什么导航栏配置要使用 TypeScript 而非静态 JSON它需要 Node 的fs/path模块做运行时读取。每个语言的导航栏对象结构一致例如英文导航栏包含 Guide、Reference 两个主项以及一个以getVersion()为标题的下拉菜单内含 Changelog 与 Contribute 链接const en [ { text: Guide, link: /guide/getting-started }, { text: Reference, link: /manage/configuration }, { text: getVersion(), items: [ { text: Changelog, link: ... }, { text: Contribute, link: /contribute/core }, ]}, ];侧边栏的目录化组织sidebars.ts同样按语言组织en / ja_jp / ko_kr / pt_br / zh_hans 五份导出每份内部再按 Guide入门→ Usage用法→ Reference参考→ Plugins插件 的逻辑分组条目通过link指向以/开头的虚拟路由路径如/manage/configurationVitePress 会将这些路径解析为docs/下对应的 Markdown 文件。需要新增文档页面时除了放置 Markdown 文件还应在对应的 sidebar 分组中登记链接否则页面不会出现在导航中。I18n多语言站点的国际化机制VitePress 对国际化i18n提供了一等支持。根配置docs/.vitepress/config.ts通过locales字段定义站点支持的所有语言包括在下拉菜单中显示的语言标签label、语言代码lang以及对应的导航栏/侧边栏配置引用。以当前仓库的真实配置为例docs/.vitepress/config.ts的locales部分asdf 文档站共维护五种语言export default defineConfig({ title: asdf, description: Manage multiple runtime versions with a single CLI tool, lastUpdated: true, locales: { 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 }, }, }, themeConfig: { search: { provider: local }, socialLinks: [{ icon: github, link: https://github.com/asdf-vm/asdf }], }, });其中root即英文默认语言其余四种为翻译语言。pt-br的lang字段写作pr-br原文如此为仓库现状新增语言时需要同时保证lang、label与导航栏/侧边栏导出一致。目录结构约定语言文件夹与 locales 键一一对应每种语言的 Markdown 内容必须存放在与locales键同名的文件夹中。也就是说ko-kr的文档位于docs/ko-kr/ja-jp位于docs/ja-jp/pt-br位于docs/pt-br/zh-hans位于docs/zh-hans/而英文文档直接位于docs/根目录下对应root键。参照当前仓库 docs/ 的实际布局其结构与约定如下docs ├─ index.md # 英文首页root locale ├─ guide/ │ ├─ getting-started.md │ └─ introduction.md ├─ manage/ │ ├─ commands.md │ ├─ configuration.md │ ├─ core.md │ ├─ dependencies.md │ ├─ plugins.md │ └─ versions.md ├─ contribute/ │ ├─ core.md │ ├─ documentation.md │ └─ ... ├─ ko-kr/ # ko-kr locale镜像英文目录结构 │ ├─ index.md │ ├─ guide/ │ ├─ manage/ │ ├─ contribute/ │ └─ ... ├─ ja-jp/ ├─ pt-br/ └─ zh-hans/值得注意的是各语言目录并非总是与英文保持完全同步从当前仓库看ja-jp、ko-kr还额外维护了guide/parts/、parts/等共享片段目录如 docs/parts/install-dependencies.md 与各语言的对应副本用于在多个页面间复用安装依赖的说明段落。贡献者新增翻译时应当先核对英文侧是否已存在对应页面再决定是新增翻译还是同步更新。新增一门语言例如法文fr-fr时的标准操作是在docs/.vitepress/navbars.ts与sidebars.ts中新增并导出fr_fr配置在docs/.vitepress/config.ts的locales中新增fr-fr键并引用上述配置新建docs/fr-fr/目录镜像英文目录结构逐页翻译本地通过npm run dev验证提交 PR 时使用docs:前缀标题。VitePress 的 i18n 还支持更细粒度的配置如title、description的语言覆盖但对文档贡献者而言掌握上述目录镜像 locales 键对齐的约定即可完成绝大多数工作。小结为 asdf 文档站点做贡献的完整链路可以概括为四步用 asdf 安装docs/.tool-versions声明的 Node.js → 在docs/下npm install→npm run dev本地编写 Markdown → 以docs: description格式的 PR 标题提交。理解 docs/.vitepress/config.ts、navbars.ts 与 sidebars.ts 三者根配置 按语言拆分的组织方式以及locales键与语言目录的一一对应关系就能在多语言站点中游刃有余地新增、修正与翻译文档。这不仅是一份文档站操作手册也是 asdf 生态用自己管理自己理念在工程实践中的一次完整展示。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考