1. 为什么我要把零散笔记折腾成一本蓝皮书我手头关于 Pi 的资料散落在十几个地方浏览器书签里躺着二十几个相关页面本地 Markdown 文件按日期命名微信收藏夹里还有一堆截图甚至有几段关键配置是记在手机备忘录里的。每次有人问我Pi 到底怎么入门我都得翻半天然后把链接一条条甩过去。这种状态持续了大半年直到某天我决定与其每次重复劳动不如把这些东西整理成一本结构化的蓝皮书开源出去谁需要谁自己看。所谓蓝皮书不是官方标准文档也不是那种板着脸的规范手册。它更像是一本由从业者自己梳理的、带有个人实践痕迹的参考读物——有原理拆解有踩坑记录有可以直接抄的配置也有这个地方我也没完全搞明白的诚实标注。Pi 这个领域目前公开的中文系统资料并不算多大部分信息散落在各种论坛帖子和零散博客里质量参差不齐。一本持续维护、结构清晰的蓝皮书对后来者来说能省下大量筛选时间。这篇文章要聊的就是我怎么从零把这件事跑起来的完整过程。核心工具链是VitePress GitHub Cloudflare Pages这套组合VitePress 负责把 Markdown 变成漂亮的文档站点GitHub 负责版本管理和协作Cloudflare Pages 负责自动构建和全球分发。整套方案零成本、零服务器运维适合任何想开源自己知识库的人。不管你是刚接触 Pi 的新手还是已经用了一段时间想系统整理经验的老手这套流程都能直接复用。我先把最终效果说清楚你写完一篇 Markdownpush 到 GitHub几分钟后线上站点自动更新。读者可以搜索、可以按侧边栏导航、可以在页面内跳转移动端也能正常阅读。整个过程你不需要买服务器不需要配 Nginx不需要折腾 SSL 证书。下面我从选型逻辑开始一步步拆。2. 技术选型为什么是 VitePress 而不是别的2.1 静态站点生成器的三条路线对比在决定用 VitePress 之前我把常见的几个方案都试了一遍。静态站点生成器大致分三类一类是通用型框架如 Hugo、Jekyll一类是文档专用型如 VitePress、Docusaurus、MkDocs还有一类是纯手写 HTML。我最终选 VitePress理由不是它最好而是它最匹配我的使用场景。方案构建速度文档特性学习曲线适合场景Hugo极快需自己配中等博客、内容站Docusaurus中等开箱即用较陡大型多版本文档MkDocs快开箱即用平缓Python 生态文档VitePress快开箱即用平缓中小型技术文档手写 HTML无无低但繁琐极简单页Hugo 的构建速度确实惊人几千篇文章几秒搞定但它的文档主题配置起来比较绕侧边栏、搜索这些都要自己折腾。Docusaurus 功能最全支持版本管理、多语言、博客插件但对我这种单版本、单语言的知识库来说太重了配置文件一大堆改个东西要翻半天文档。MkDocs 很轻但它的默认主题 Material 虽然好看定制起来要写 CSS 覆盖而且 Node 生态的插件没有 VitePress 丰富。VitePress 打动我的点很具体它基于 Vite 和 Vue构建快热更新几乎无感默认主题就是为文档设计的侧边栏、导航、搜索、代码高亮、暗色模式全部内置配置文件是一个config.mjs结构清晰改起来直观而且它输出的是纯静态文件部署到任何静态托管平台都行。2.2 VitePress 的目录结构设计逻辑VitePress 的目录约定很简单但理解它的设计逻辑能帮你少走弯路。核心就两个目录.vitepress放配置和主题定制其他目录放你的 Markdown 内容。我一开始把配置和内容混在一起后来发现分开之后清爽很多。pi-bluebook/ ├── .vitepress/ │ ├── config.mjs # 站点配置 │ ├── theme/ │ │ ├── index.js # 主题入口 │ │ └── custom.css # 自定义样式 │ └── cache/ # 构建缓存不用管 ├── index.md # 首页 ├── guide/ │ ├── index.md # 指南首页 │ ├── getting-started.md │ └── configuration.md ├── reference/ │ ├── index.md │ └── api.md └── package.json这里有个容易踩的坑.vitepress目录下的 Markdown 文件不会被当作页面处理它是配置区。你的内容必须放在.vitepress外面。我一开始把一篇笔记放进了.vitepress里构建完发现页面根本不存在排查了半小时才反应过来。另一个设计点是路由和文件路径的映射关系。guide/getting-started.md对应的访问路径就是/guide/getting-started不需要额外配置。首页是根目录的index.md如果你想让某个子目录的index.md成为该目录的入口访问/guide/就能看到。这种约定优于配置的思路减少了大量重复劳动。2.3 为什么不用现成的文档平台有人可能会问直接用语雀、Notion、飞书文档不香吗为什么要自己搭我的理由有三条。第一数据自主权。平台可能改政策、可能收费、可能关停我的知识库放在自己控制的仓库里随时可以迁移。第二定制自由度。我想加什么交互、想怎么组织导航、想嵌入什么组件自己说了算。第三也是最重要的一条——开源协作。放在 GitHub 上任何人都可以提 Issue 指出错误可以提 PR 补充内容这种开放性是一本蓝皮书能持续进化的关键。平台文档适合个人快速记录但如果你想做一本有长期价值、能被社区共建的参考读物自建静态站点是更合适的选择。而且这套方案的成本是零维护成本也极低一次配置好之后你只需要专注写内容。3. 从空仓库到第一篇文章上线3.1 初始化项目时最容易忽略的三个细节初始化 VitePress 项目本身很简单官方文档给了一条命令但我在实际操作中发现有三个细节如果一开始不注意后面会返工。第一个是 Node 版本。VitePress 要求 Node 18 以上我本地默认是 16跑npm install直接报错。建议先用node -v确认如果版本不够用 nvm 切一下。这个坑很基础但确实有人会卡在这里。第二个是包管理器选择。npm、yarn、pnpm 都能用但如果你打算用 Cloudflare Pages 自动构建要注意它默认用的是 npm。我本地习惯用 pnpm结果 lock 文件格式和 Cloudflare 预期的不一致构建时依赖装不上。后来统一改成 npm问题消失。如果你坚持用 pnpm需要在 Cloudflare 的构建命令里显式指定。第三个是package.json里的脚本配置。默认只有docs:dev和docs:build我建议加一个docs:preview本地构建完先预览一下确认没问题再 push。因为开发模式和构建模式的渲染结果偶尔会有差异比如某些动态导入的组件在构建时才会暴露问题。{ scripts: { docs:dev: vitepress dev, docs:build: vitepress build, docs:preview: vitepress preview } }初始化完成后先跑npm run docs:dev浏览器打开localhost:5173看到默认首页就说明环境没问题。这时候别急着写内容先把配置文件的结构理清楚。3.2 config.mjs 里真正需要改的字段VitePress 的配置文件看起来字段很多但一个文档站点真正需要改的其实就那几个。我把我的配置拆开讲每个字段为什么这么设。import { defineConfig } from vitepress export default defineConfig({ title: Pi 蓝皮书, description: 一本由社区共建的 Pi 实践参考, lang: zh-CN, base: /, head: [ [link, { rel: icon, href: /favicon.ico }] ], themeConfig: { nav: [ { text: 指南, link: /guide/ }, { text: 参考, link: /reference/ } ], sidebar: { /guide/: [ { text: 入门, items: [ { text: 快速开始, link: /guide/getting-started }, { text: 基础配置, link: /guide/configuration } ] } ] }, search: { provider: local }, socialLinks: [ { icon: github, link: https://github.com/yourname/pi-bluebook } ] } })base这个字段值得单独说。如果你部署在根域名下保持/就行。但如果部署在子路径下比如example.com/pi-bluebook/这里必须改成/pi-bluebook/否则所有资源路径都会 404。Cloudflare Pages 默认部署在根路径所以用/没问题但如果你之后绑定了自定义域名并放在子目录记得回来改。search.provider设为local会启用本地搜索VitePress 会在构建时生成一个搜索索引。这个功能对小规模文档完全够用不需要接第三方搜索服务。索引大小和你的内容量成正比几百篇文章以内都没问题。侧边栏的配置逻辑是按路径前缀匹配的。/guide/下的页面用第一套侧边栏/reference/下的用另一套。这种设计让你可以为不同板块设置不同的导航结构很灵活。我一开始把所有页面塞进一个侧边栏后来内容多了之后发现根本没法看拆开之后清晰多了。3.3 写第一篇 Markdown 时的格式约定VitePress 用的是标准 Markdown但加了一些扩展语法。我建议在写第一篇内容之前先定好一套格式约定后面所有文章都遵循这样整本书的风格才统一。我的约定是这样的每篇文章开头用一级标题其实在 VitePress 里会被渲染成页面标题然后直接进入正文不写本文将介绍这种废话。代码块必须标注语言方便高亮。重要提示用引用块不要用加粗代替。表格用来做对比不用来做布局。# 快速开始 这里直接说怎么装、怎么跑不铺垫。 ## 环境要求 - Node 18 - npm 或 pnpm ## 安装步骤 1. 克隆仓库 2. 安装依赖 3. 启动开发服务器 注意如果 Node 版本不够先升级再继续。有一个细节很多人不知道VitePress 支持在 Markdown 里直接写 Vue 组件。这意味着你可以在文档里嵌入交互式示例比如一个可折叠的提示框、一个带标签页的代码示例。这个能力在写技术文档时特别有用但不要滥用否则文档会变得像应用而不是读物。我个人的原则是能用纯 Markdown 表达清楚的就不用组件。组件只在确实需要交互的时候才引入比如多语言代码切换、可运行的示例。保持文档的可读性比炫技重要。4. 用 GitHub 管理内容版本与协作4.1 仓库结构的分支策略把内容放到 GitHub 上第一件事是决定分支策略。对于一本个人维护的蓝皮书我不建议搞太复杂的分支模型。main分支就是发布分支所有内容合并到这里就会触发自动部署。日常写作可以直接在main上提交或者开一个draft分支写草稿写完再合并。如果你打算接受社区贡献那需要多一层考虑。外部贡献者不能直接推main他们只能 fork 你的仓库改完之后提 PR。你需要 review 之后才能合并。这个过程 GitHub 原生支持不需要额外工具。我的做法是main分支保护开启要求 PR 才能合并但允许我自己直接推管理员权限。这样日常写作不受影响同时外部贡献走 PR 流程。分支保护规则在仓库的 Settings → Branches 里配置勾选Require a pull request before merging即可。还有一个细节.vitepress/cache和node_modules必须加到.gitignore里。前者是构建缓存后者是依赖都不应该进仓库。我见过有人把node_modules提交上去仓库瞬间几百 MBclone 一次要等半天。node_modules/ .vitepress/cache/ .vitepress/dist/ .DS_Store4.2 提交信息的规范与自动化检查提交信息看起来是小事但当你的仓库有几百次提交之后一份清晰的提交历史能帮你快速定位某段内容是什么时候加的、为什么加。我用的规范很简单类型: 简短描述。类型就几种feat新增内容fix修正错误docs文档调整chore杂项。feat: 添加 Pi 基础配置章节 fix: 修正快速开始里的命令错误 docs: 调整侧边栏顺序如果你想让这件事更自动化可以加一个 GitHub Action在 PR 提交时检查提交信息格式。但这属于锦上添花个人项目不必强求。我一开始配了后来觉得每次提交都要想格式太累就改成手动遵守了。工具是为人服务的不要反过来。真正值得配的自动化是链接检查。文档里难免有外部链接时间久了有些会失效。可以加一个定时任务每周跑一次链接检查发现死链就开 Issue 提醒自己。这个用 GitHub Actions 很容易实现网上有现成的 action 可以直接用。4.3 用 Issue 和 PR 做内容迭代开源一本蓝皮书最大的价值不是我写完了而是它能持续被修正和补充。Issue 和 PR 就是实现这个的机制。我在仓库里设了几个 Issue 模板一个是内容纠错一个是内容建议一个是新增章节请求。这样别人提 Issue 的时候有章可循我也能快速分类处理。PR 的处理流程我定了几条规则第一任何 PR 必须说明改了什么、为什么改第二涉及技术内容的 PR我会实际验证一遍再合并第三纯格式调整的 PR 直接合并不纠结。这些规则写在CONTRIBUTING.md里让贡献者提前知道预期。有一个经验值得分享不要等到内容完美了才开源。我一开始想先把所有章节写完再公开结果拖了两个月还没写完。后来改成先公开框架和前三章边写边接受反馈反而写得更快因为有人催更、有人指出错误形成了一种正向压力。开源的本质是协作不是展示成品。5. Cloudflare Pages 自动部署的完整链路5.1 连接仓库与构建设置Cloudflare Pages 的部署流程很直观登录 Cloudflare 控制台进入 Pages点创建项目选择连接 GitHub 仓库。第一次连接需要授权 Cloudflare 访问你的 GitHub 账号授权之后选择对应的仓库即可。关键在构建设置这一步。三个字段必须填对字段值说明构建命令npm run docs:build执行 VitePress 构建输出目录.vitepress/distVitePress 默认输出位置Node 版本18或20在环境变量里设NODE_VERSION输出目录这个字段最容易填错。VitePress 默认把构建结果放在.vitepress/dist不是dist也不是public。我第一次填了dist构建成功但页面 404排查了半天才发现是输出目录不对。Node 版本通过环境变量设置。在 Pages 项目的 Settings → Environment variables 里加一个NODE_VERSION值设为20。如果不设Cloudflare 可能用默认版本而默认版本不一定满足 VitePress 的要求。5.2 构建失败时的排查顺序自动部署最让人抓狂的就是构建失败而 Cloudflare 的日志有时候不够详细。我总结了一套排查顺序按这个顺序走大部分问题都能定位。第一步看构建日志的最后几行。错误信息通常在那里。如果是command not found说明构建命令写错了或者依赖没装。如果是Cannot find module说明某个依赖缺失检查package.json。第二步本地复现。在本地跑一遍npm run docs:build如果本地也失败那就是代码问题和 Cloudflare 无关。如果本地成功但 Cloudflare 失败那大概率是环境差异重点查 Node 版本和依赖安装方式。第三步检查 lock 文件。如果你本地用 pnpm 但 Cloudflare 用 npmlock 文件不匹配会导致依赖装不上。解决办法是统一包管理器或者在 Cloudflare 的构建命令里显式指定pnpm install pnpm docs:build。第四步清理缓存重试。Cloudflare Pages 会缓存依赖有时候缓存损坏会导致奇怪的错误。在项目设置里有个清除缓存并重新部署的选项试一下。我遇到过一次构建失败日志只显示Build failed没有任何细节。后来发现是某篇 Markdown 里有一个未闭合的代码块导致解析器报错但错误信息被吞了。这种问题只能靠本地构建来定位所以养成 push 前本地构建一遍的习惯很重要。5.3 自定义域名与 HTTPS 的配置Cloudflare Pages 默认给一个xxx.pages.dev的域名可以直接用。但如果你想让蓝皮书有个正式地址可以绑自定义域名。过程很简单在 Pages 项目的 Custom domains 里添加你的域名然后去域名注册商那里加一条 CNAME 记录指向xxx.pages.dev。HTTPS 是自动的Cloudflare 会自动签发证书你不需要做任何事。证书续期也是自动的。这一点比自建服务器省心太多不用折腾 Lets Encrypt不用设 cron 任务。有一个细节如果你在 Cloudflare 上也管理 DNS添加自定义域名时它会自动帮你配好记录一步到位。如果 DNS 在别处就需要手动加 CNAME。建议把 DNS 也迁到 Cloudflare管理起来方便而且免费套餐就够用。绑定域名之后记得回 VitePress 配置里检查base字段。如果域名是根域名base保持/如果是子路径要相应修改。这个前面提过但确实有人绑完域名发现样式全丢了就是base没改。6. 内容组织与长期维护的实战心得6.1 章节划分的粒度控制一本蓝皮书能不能用很大程度上取决于章节划分是否合理。太粗读者找不到具体内容太细侧边栏长得像目录树翻起来累。我的经验是按学习路径划分一级章节按具体主题划分二级章节。比如 Pi 蓝皮书的一级章节可以是入门指南、核心概念、配置参考、实战案例、常见问题。每个一级章节下面再分二级。入门指南下面是环境搭建、第一个项目、基础命令。核心概念下面是架构说明、关键术语、工作原理。这样读者从入门到深入有一条清晰的路径。粒度控制的一个实用标准是每个二级页面的阅读时间控制在 5 到 15 分钟。太短说明内容不够可以合并太长说明主题太大应该拆分。我一开始把配置写成一个巨长的页面后来拆成基础配置高级配置配置示例三个页面阅读体验好很多。还有一个技巧用侧边栏的折叠功能。VitePress 支持侧边栏分组折叠把不常用的分组默认折叠起来让侧边栏保持清爽。这个在config.mjs的 sidebar 配置里加collapsed: true就行。6.2 让内容持续更新的机制开源项目最大的挑战不是开始而是坚持。我见过太多仓库初始几篇内容质量很高然后半年没更新最后变成僵尸项目。为了避免这种情况我给自己定了几个机制。第一把大目标拆成小任务。不要想着写完一整章而是今天补一个小节。小任务容易完成完成之后有成就感能形成正反馈。我在 GitHub 上用 Projects 看板管理待写内容每完成一个就拖到已完成列看着进度条前进很解压。第二建立反馈循环。每篇文章末尾加一个这篇内容对你有帮助吗的反馈入口读者可以一键提 Issue 说哪里不清楚。有人反馈就说明有人在看这种互动是持续更新的动力。第三定期回顾。我每个月花半小时过一遍所有 Issue 和 PR处理积压的问题。不需要每天看但也不能完全不管。定个日历提醒到时间就处理。第四接受不完美。有些章节可能永远写不完有些内容可能过时了但没来得及更新。这很正常。重要的是整体在往前走而不是追求每一页都完美。我在仓库的 README 里明确写了这是一本持续更新中的文档部分内容可能不完整降低读者预期也给自己减压。6.3 处理内容过时与版本迭代技术类内容有个绕不开的问题过时。Pi 相关的工具链、配置方式、最佳实践都可能随时间变化。如果不处理蓝皮书会逐渐失去参考价值。我的做法是给每篇文章加一个最后更新时间戳放在页面底部。VitePress 支持通过 frontmatter 或者自定义组件来实现。读者看到时间戳自己判断内容的新鲜度。如果某篇内容超过一年没更新我会在页面顶部加一个提示这篇内容可能已过时请以最新文档为准。对于确实过时的内容我不建议直接删除而是标记为归档。因为有些旧版本的配置方式对还在用旧版本的人仍然有用。归档的内容放在单独的目录里侧边栏里折叠起来不干扰新读者但需要的人能找到。版本迭代的另一个策略是重大变更时开新分支。比如 Pi 从 v1 升级到 v2配置方式完全变了我就在仓库里开一个v2分支main分支继续维护 v1 的内容等 v2 稳定了再合并。这样两版读者都能找到对应的文档。VitePress 本身也支持多版本文档但配置起来稍复杂小项目用分支策略就够了。7. 我踩过的那些坑和对应的解法7.1 路径与 base 配置引发的资源 404这是我最开始踩的坑也是最典型的。本地开发一切正常部署到 Cloudflare 之后页面能打开但 CSS 和 JS 全部 404页面变成纯文本。原因就是base配置和实际部署路径不匹配。VitePress 在构建时会根据base生成所有资源的引用路径。如果base是/资源路径就是/assets/xxx.js如果base是/pi-bluebook/资源路径就是/pi-bluebook/assets/xxx.js。部署在根域名下但base设成了子路径或者反过来都会导致 404。排查方法很简单打开浏览器开发者工具看 Network 面板里 404 的请求路径对比你的实际部署路径就能判断base该设成什么。记住一个原则base的值必须和站点实际访问的根路径一致末尾要带斜杠。7.2 Markdown 扩展语法在构建时的静默失败VitePress 支持一些扩展语法比如自定义容器、代码块行高亮、导入代码片段。这些语法在开发模式下如果写错了有时候不会报错只是渲染结果不对。但构建时可能会直接失败而且错误信息很隐晦。我遇到过一次某个自定义容器的闭合标记写错了开发模式下看起来正常构建时整个页面空白。后来逐个文件排查才找到。从那以后我养成了一个习惯每次写完一篇内容先跑npm run docs:build确认构建通过再 push。构建通过之后再用npm run docs:preview本地预览一遍确认渲染结果正确。这个习惯看起来多了一步但能避免很多push 之后等构建、构建失败再改、再 push的来回折腾。本地构建一次也就几秒钟比等 Cloudflare 构建快多了。7.3 大文件与图片资源的处理策略文档里难免要放图片。图片如果直接提交到 Git 仓库仓库体积会迅速膨胀。我一开始没注意放了几十张截图仓库从几 MB 涨到一百多 MBclone 一次要等很久。解决办法有几个。一是压缩图片用工具把 PNG 转成 WebP体积能减少一半以上。二是把图片放到外部图床仓库里只存链接。但图床有失效风险而且依赖第三方服务。三是用 Git LFS把大文件交给 LFS 管理仓库本身保持轻量。我最终选了方案一加方案三的组合图片先压缩然后如果单张超过 500KB就用 Git LFS 管理。Cloudflare Pages 支持 LFS构建时会自动拉取。这样仓库保持轻量图片也能正常显示。还有一个细节图片路径要用相对路径不要用绝对路径。相对路径在本地开发和线上部署时都能正确解析绝对路径容易因为base配置而出问题。7.4 搜索索引过大导致的构建缓慢VitePress 的本地搜索会在构建时生成一个索引文件。内容少的时候没问题但当你的文档有几百篇、总字数几十万的时候索引文件会变得很大构建时间明显变长而且浏览器加载搜索功能时会卡顿。我的文档写到大概一百多篇的时候开始感觉到这个问题。构建时间从十几秒涨到一分多钟搜索框输入时也有延迟。解决办法是调整搜索配置排除一些不需要索引的页面比如归档内容、更新日志。search: { provider: local, options: { exclude: [/archive/**, /changelog/**] } }排除之后索引体积小了很多构建时间和搜索响应都恢复正常。如果你内容量特别大可以考虑换成 Algolia 这类第三方搜索服务但对大多数个人知识库来说本地搜索优化一下就够了。8. 关于开源协作与社区运营的几点体会8.1 如何写出让人愿意贡献的文档开源文档能不能吸引贡献者很大程度上取决于门槛和氛围。门槛低、氛围好的项目自然有人愿意提 PR。我做了几件事来降低门槛。第一写一份清晰的CONTRIBUTING.md告诉贡献者怎么搭环境、怎么提 PR、有什么规范。不要假设他们知道这些。第二给一些good first issue标签的简单任务让新人可以练手。比如修正错别字、补充一个示例、翻译一段内容。第三及时回应。有人提了 PR哪怕暂时没时间细看也先回一句收到了我这两天看让对方知道有人在。冷处理是劝退贡献者最快的方式。还有一点不要对贡献内容过于苛刻。有人愿意花时间帮你改进本身就是好事。格式不完美可以后面调内容有小错可以改但如果一开始就挑三拣四人家下次就不来了。我自己的原则是只要方向对先合并再优化。8.2 许可证选择与内容引用规范开源不等于放弃版权。你需要选一个许可证明确别人可以怎么用你的内容。对于文档类项目常见的选择是 CC BY-SA 4.0 或 MIT。CC BY-SA 要求署名且衍生作品使用相同许可适合希望内容保持开放的场景。MIT 更宽松几乎不限制使用方式。我选的是 CC BY-SA 4.0因为蓝皮书本身引用了不少社区资料我希望它保持开放衍生作品也保持开放。许可证文件放在仓库根目录文件名LICENSE内容用官方模板。引用规范也很重要。如果我在文档里引用了别人的内容必须注明来源。这既是对原作者的尊重也是文档可信度的保证。我在每篇引用了外部资料的文章末尾加一个参考来源小节列出链接和作者。如果引用量大就单独开一个致谢页面。8.3 从个人项目到社区项目的过渡信号什么时候该把个人项目变成社区项目我的判断标准是当你发现自己一个人维护不过来或者有人主动提出想参与的时候。具体信号包括Issue 数量持续增长但你处理不过来、有人提了高质量的 PR、有人在其他地方推荐你的项目。这时候你需要做一些调整。比如把仓库从个人账号迁移到组织账号设置多个维护者建立更正式的决策流程。但这些调整不要过早做否则会消耗大量精力在管理上反而没时间写内容。我个人的节奏是先自己写写到有稳定读者和贡献者了再考虑社区化。过渡过程中最重要的是明确谁说了算。开源项目常见的问题是决策权不清导致分歧时无法推进。我的做法是核心方向我自己定具体内容贡献者可以自由发挥。这样既保持了项目的连贯性又给了贡献者空间。9. 后续可以继续扩展的方向这套流程跑通之后我陆续加了一些扩展。一个是多语言支持VitePress 内置了 i18n 能力配置一下就能支持中英文切换。我目前只做了中文但结构留好了以后想加英文版随时可以。另一个是版本化文档通过目录结构区分不同版本的 Pi 文档读者可以切换查看。还有一个我觉得很有价值的方向是交互式示例。VitePress 支持在 Markdown 里嵌入 Vue 组件这意味着你可以在文档里放一个可运行的配置生成器读者填几个参数就能生成对应的配置代码。这种交互式文档比纯文字说明直观得多但开发成本也高适合核心章节。最后如果你想让蓝皮书更容易被找到可以做一些 SEO 优化。VitePress 支持为每个页面配置 meta 标签在 frontmatter 里加description和keywords就行。另外把站点提交到搜索引擎加一个sitemap.xml都能提升曝光。这些属于锦上添花内容质量才是根本。我个人在实际操作中的体会是开源一本蓝皮书技术门槛其实不高难的是持续投入。工具链只是载体真正有价值的是你在这个领域积累的经验和踩过的坑。把这些东西系统地整理出来让后来者少走弯路这件事本身就值得做。至于用 VitePress 还是别的工具用 Cloudflare 还是别的平台都是次要的。先写起来再慢慢优化。
