企业官网建设流程全解析

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 install

asdf 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/.gitignore），npm run preview用于本地预览构建产物。写文档时一般用不到这两条，但 CI 构建和本地验证时必不可少。

提交流程：Pull Request、发布与 Conventional Commits

asdf 使用自动化的发布流水线，它依赖 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/configuration），VitePress 会将这些路径解析为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）时的标准操作是：

1. 在docs/.vitepress/navbars.ts与sidebars.ts中新增并导出fr_fr配置；
2. 在docs/.vitepress/config.ts的locales中新增"fr-fr"键，并引用上述配置；
3. 新建docs/fr-fr/目录，镜像英文目录结构逐页翻译；
4. 本地通过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