从零构建开源蓝皮书：VitePress + GitHub + Cloudflare Pages 实战

1. 为什么我要把零散笔记折腾成一本"蓝皮书"

我手头关于 Pi 的资料，散落在十几个地方：浏览器书签里躺着二十几个相关页面，本地 Markdown 文件按日期命名，微信收藏夹里还有一堆截图，甚至有几段关键配置是记在手机备忘录里的。每次有人问我"Pi 到底怎么入门"，我都得翻半天，然后把链接一条条甩过去。这种状态持续了大半年，直到某天我决定：与其每次重复劳动，不如把这些东西整理成一本结构化的"蓝皮书"，开源出去，谁需要谁自己看。

所谓"蓝皮书"，不是官方标准文档，也不是那种板着脸的规范手册。它更像是一本由从业者自己梳理的、带有个人实践痕迹的参考读物——有原理拆解，有踩坑记录，有可以直接抄的配置，也有"这个地方我也没完全搞明白"的诚实标注。Pi 这个领域目前公开的中文系统资料并不算多，大部分信息散落在各种论坛帖子和零散博客里，质量参差不齐。一本持续维护、结构清晰的蓝皮书，对后来者来说能省下大量筛选时间。

这篇文章要聊的，就是我怎么从零把这件事跑起来的完整过程。核心工具链是VitePress + GitHub + Cloudflare Pages这套组合：VitePress 负责把 Markdown 变成漂亮的文档站点，GitHub 负责版本管理和协作，Cloudflare Pages 负责自动构建和全球分发。整套方案零成本、零服务器运维，适合任何想开源自己知识库的人。不管你是刚接触 Pi 的新手，还是已经用了一段时间想系统整理经验的老手，这套流程都能直接复用。

我先把最终效果说清楚：你写完一篇 Markdown，push 到 GitHub，几分钟后线上站点自动更新。读者可以搜索、可以按侧边栏导航、可以在页面内跳转，移动端也能正常阅读。整个过程你不需要买服务器，不需要配 Nginx，不需要折腾 SSL 证书。下面我从选型逻辑开始，一步步拆。

2. 技术选型：为什么是 VitePress 而不是别的

2.1 静态站点生成器的三条路线对比

在决定用 VitePress 之前，我把常见的几个方案都试了一遍。静态站点生成器大致分三类：一类是通用型框架如 Hugo、Jekyll，一类是文档专用型如 VitePress、Docusaurus、MkDocs，还有一类是纯手写 HTML。我最终选 VitePress，理由不是它"最好"，而是它最匹配我的使用场景。

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提交上去，仓库瞬间几百 MB，clone 一次要等半天。

node_modules/ .vitepress/cache/ .vitepress/dist/ .DS_Store

4.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 账号，授权之后选择对应的仓库即可。

关键在构建设置这一步。三个字段必须填对：

输出目录这个字段最容易填错。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 用 npm，lock 文件不匹配会导致依赖装不上。解决办法是统一包管理器，或者在 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 会自动签发证书，你不需要做任何事。证书续期也是自动的。这一点比自建服务器省心太多，不用折腾 Let's 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 涨到一百多 MB，clone 一次要等很久。

解决办法有几个。一是压缩图片，用工具把 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 还是别的平台，都是次要的。先写起来，再慢慢优化。