企业官网建设流程全解析

如何用 VitePress 本地开发与构建 asdf 文档站

【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang & more项目地址: https://gitcode.com/GitHub_Trending/as/asdf

asdf 的文档站（仓库中的docs/目录）使用 VitePress 作为静态站点生成器构建。如果你要修改 asdf 的文档内容、导航/侧边栏配置或主题，需要在本地完成一套固定流程：用 asdf 安装文档工具依赖的 Node.js，在docs/下安装 npm 依赖，启动开发服务器编辑，然后构建出静态产物验证。本文按这条路径走一遍完整的本地开发与构建过程。

准备条件

在开始之前确认两点：

• 本机已安装 asdf，且可以使用asdf命令行；
• 文档站工具链由 asdf 管理：docs/.tool-versions中固定了nodejs 22.10.0。

docs/package.json声明了文档站的全部 npm 依赖：vitepress ^1.6.4、prettier ^3.9.6、@types/node ^26.1.2，并提供了dev、build、preview、fmt四个脚本。

克隆仓库并安装 Node.js

git clone https://gitcode.com/GitHub_Trending/as/asdf cd asdf

文档站的开发工具版本通过docs/.tool-versions管理，需要先用 asdf 添加 nodejs 插件，再在docs/目录下安装对应版本：

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs cd docs asdf install

asdf install会读取当前目录的.tool-versions并安装其中声明的工具版本，即nodejs 22.10.0。

安装 npm 依赖

仍然在docs/目录下：

npm install

这会根据docs/package.json与docs/package-lock.json安装 vitepress 等开发依赖。仓库的 CI（.github/workflows/documentation.yml）在构建文档站时执行的也是同一条npm install，并配合package-lock.json做依赖缓存，所以本地执行同样一条命令即可复现 CI 环境。

启动本地开发服务器

npm run dev

该脚本等价于vitepress dev，启动后修改任意 Markdown 或配置文件即可在浏览器中查看渲染结果。站点结构主要由以下几个文件决定：

• docs/.vitepress/config.ts：站点根配置，包含title、description、lastUpdated、多语言locales以及search: { provider: "local" }的本地搜索设置；
• docs/.vitepress/navbars.ts：各语言的导航栏配置，按语言分别导出（en、ja_jp、ko_kr、pt_br、zh_hans）；
• docs/.vitepress/sidebars.ts：各语言的侧边栏配置；
• docs/.vitepress/theme/index.ts：主题入口，基于vitepress/theme默认主题引入 custom.css（其中定义了--vp-c-brand-1等品牌色变量）。

注意：贡献指南 正文中把这几个配置写作.vitepress/config.js、navbars.js、sidebars.js，但仓库中的实际文件是.ts后缀（docs/package.json里fmt脚本的 prettier 目标同样指向.ts文件），以仓库实际文件为准。

另外，navbars.ts中的导航菜单会调用getVersion()从仓库根目录的.release-please-manifest.json读取版本号，读取失败会直接process.exit(1)。因此克隆下来的仓库中该文件（当前内容为0.20.0）不能缺失，否则站点配置无法加载。

修改多语言内容（可选）

如果任务涉及翻译或新增语言，VitePress 的多语言由config.ts的locales驱动：每个语言目录名必须与locales的键一致，例如root对应英文根目录、zh-hans对应docs/zh-hans/。新增语言时需要为该目录补齐与root相对应的 Markdown 文件集合，并在navbars.ts/sidebars.ts中补充对应语言的配置项。

构建前格式化

提交前执行：

npm run fmt

它会对.vitepress/{config,navbars,sidebars}.ts以及.vitepress/theme/**下的文件运行prettier --write，只覆盖文档站配置与主题代码，不影响 Markdown 内容。

构建并验证产物

npm run build

构建结果输出到docs/.vitepress/dist。构建完成后可以用：

npm run preview

本地预览构建出的静态站点，确认页面、导航、侧边栏和语言切换都正常。

docs/.vitepress/dist也是官方部署的唯一产物目录：CI 在docs/目录执行npm run build后，把 CNAME（内容为asdf-vm.com）复制进 dist，再将整个 dist 目录部署到 gh-pages 分支。本地构建时不需要 CNAME，它只在部署环节使用。

提交变更

文档变更的 PR 标题必须使用 Conventional Commit 的docs类型，格式为：

docs: <description>

asdf 的自动化发布流水线依赖 PR 标题中的 Conventional Commits 约定，标题不符合格式会影响自动化流程。

限制与说明

• npm run build与npm run dev都必须在docs/目录下执行（npm 脚本的默认工作目录就是docs/）；
• asdf 与 Node.js 版本以docs/.tool-versions为准，不要在文档开发中自行改用其他 Node.js 版本，否则可能与 lockfile 及 CI 行为不一致；
• 文档站只支持locales中已声明的语言，新增语言属于“可选扩展”，不是本地开发的必要步骤。

【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang & more项目地址: https://gitcode.com/GitHub_Trending/as/asdf