📚 场景引入
小白：“我的知识星球功能越来越多，我自己都快记不住怎么用了，更别说让别人看懂……” 爱好者：“你需要 Wiki——给项目写一本‘活的使用手册’，随着项目一起生长，永不掉队。” 真实痛点：
- README 太长，挤成一团，找不到重点
- 安装步骤、配置说明、功能详解混在一起
- 想写详细文档，但不知道该放在哪里
- 项目更新了，文档却没同步更新
Wiki 就是你的项目说明书、菜谱、维护手册三合一。
📖 核心概念（比喻版）
Wiki 是什么？
想象你买了一个复杂的乐高套装：
- 项目代码 = 乐高积木本身
- README = 包装盒背面的简介（吸引你购买）
- Wiki = 厚厚的拼装说明书（一步一步教你搭完）
特点：
- 结构化：分成很多页面，层次分明
- 易维护：在线编辑，随时更新
- 可协作：任何人都可以帮忙改进
- 永久链接：每个页面都有固定网址，方便分享
README vs Wiki
场景 README（首页） Wiki（说明书库） 第一印象 ✅ 精简介绍，吸引人 ❌ 太长了看不完 详细教程 ❌ 篇幅有限 ✅ 分章节详细写 安装配置 ✅ 只写最简步骤 ✅ 多系统、多场景全覆盖 API 说明 ❌ 不适合放 ✅ 专门页面详细列 更新频率 较高 随功能更新
一句话：README 是门面，Wiki 是里子。
🚀 手把手教学：开启并编写你的第一个 Wiki
步骤1：开启 Wiki 功能
- 进入你的 Gitee 仓库
- 在导航栏找到 “Wiki” 选项卡
- 如果是第一次，会提示“初始化 Wiki”，点击确认
步骤2：认识 Wiki 界面
你会看到一个类似这样的编辑器：
+------------------------------------------------+
| 编辑 Wiki 页面 |
+------------------------------------------------+
| 页面标题: [_________________________] |
| |
| 内容 (Markdown): |
| # 标题 |
| ## 二级标题 |
| - 列表项 |
| 代码块 |
| |
| 提交信息: [更新 Wiki 页面] |
| |
| [保存] |
+------------------------------------------------+
关键点：
- 每个页面都有一个唯一路径，如 "home"、 "installation"
- 页面之间可以用 "链接文本" 互链
- 支持 Markdown，和你写 README 一样简单
步骤3：创建“知识星球”的主页
页面路径： "home"（默认首页）
内容：
🌟 知识星球 - 我的数字花园
欢迎来到我的知识星球！这是一个个人知识管理系统，帮助你：
- 📝 记录学习笔记
- 🌐 发布个人博客
- ⭐ 收藏优质文章
- 🎨 自定义主题风格
📂 快速导航
- [[安装指南]]
- [[使用教程]]
- [[常见问题]]
- [[更新日志]]
注意： "[[页面名]]" 是 Wiki 特有的内部链接语法，会自动渲染成链接。
步骤4：创建详细的安装指南
点击“新建页面”，路径填 "installation"：
📦 安装指南
环境要求
- Node.js 16+（可选，未来扩展用）
- 现代浏览器（Chrome/Edge/Firefox/Safari）
🚀 最简单用法（纯静态）
- 下载仓库 ZIP 或克隆：
bash
git clone "gitee.com/" (gitee.com/)你的用户名/my-k…
- 用 VSCode 或其他编辑器打开文件夹
- 双击
index.html即可在浏览器中打开
🔧 开发者模式（可选）
如果需要本地服务器：
bash
cd my-knowledge-garden
python -m http.server 8000
或
npx serve .
访问 http://localhost:8000 查看。
保存后，回到 "home" 页面，你会发现 "[[安装指南]]" 已经变成了可点击的链接！
🧩 应用到“知识星球”：搭建完整文档体系
推荐页面结构
📖 Wiki ├── home（首页）------------------------------------- │ - 项目简介、价值、快速导航 │ ├── installation（安装）------------------------------ │ - 各种环境的安装步骤、依赖说明 │ ├── usage（使用教程）-------------------------------- │ - 功能一步步详解，带截图 │ - 写作建议、博客发布流程 │ ├── faq（常见问题）---------------------------------- │ - Q&A 形式，不断积累 │ ├── changelog（更新日志）---------------------------- │ - 按版本记录重大变更 │ └── development（开发者指南）----------------------- - 如何参与贡献、代码规范、架构说明
实际操作：为“夜间模式”写使用说明
创建页面 "usage-themes"：
🎨 主题与夜间模式
🌙 夜间模式
本项目支持一键切换夜间模式：
- 在页面右下角找到月亮图标按钮
- 点击即可切换深色/浅色主题
- 系统会自动记住你的偏好
🎭 自定义主题
如果你想修改颜色，编辑 css/styles.css 中的颜色变量：
css
:root {
--bg-color: #ffffff;
--text-color: #333333;
}
然后在 "usage" 页面里加上链接到这个页面。
🔄 让 Wiki 活起来：文档即产品
文档也要“版本控制”
- 每次修改 Wiki，Gitee 都会记录版本历史
- 可以查看谁、何时、改了哪里
- 可以回滚到旧版本，防止误删
文档与代码同步
黄金法则：
每当添加新功能（如收藏夹），就要：
- 在 Wiki 里新建或更新对应页面
- 在 PR 描述里注明“已更新 Wiki”
- 把 Wiki 链接附在 README 里 效果：你的项目不仅能用，而且好学、好维护。
❓ 常见问题与误区
Q1：Wiki 和 README 内容重复怎么办？
策略：
- README：只放最重要、最概括的信息
- Wiki：放详细、分章节的内容
- README 末尾加上“📚 "详细文档请见 Wiki" (./wiki)”
Q2：Wiki 页面多了会不会乱？
不会，因为有侧边栏目录：
- Gitee Wiki 会自动生成层级目录
- 你可以自定义侧边栏顺序（通过 "_sidebar.md" 文件）
- 内部链接让页面形成网络，而不是孤岛
Q3：别人能编辑我的 Wiki 吗？
取决于仓库权限：
- 公开仓库：默认任何人可编辑（可关闭）
- 私有仓库：只有协作者可编辑
- 企业/组织仓库：按团队权限控制
Q4：Wiki 能被搜索引擎搜到吗？
公开仓库的 Wiki 可以被 Google/Baidu 收录，这其实是你项目的免费宣传渠道。
常见误区：
- 误区：等项目做完了再写 Wiki后果：细节忘光了，写出来的文档干巴巴
- 误区：Wiki 写得像代码注释后果：非技术人员根本看不懂
- 误区：从不更新 Wiki后果：文档落后于代码，反而误导人
📝 今日收获总结
✅ 理解 Wiki 的价值：可生长的项目说明书
✅ 学会开启和使用 Gitee Wiki：页面、路径、内部链接
✅ 搭建文档骨架：首页、安装、使用、FAQ、更新日志
✅ 掌握文档同步原则：代码更新 → 文档更新 → 记录版本
你的知识星球现在“会说话”了：
📁 my-knowledge-garden ├── 📖 README.md（门面） ├── 🌐 wiki/（完整的说明书库） │ ├── home │ ├── installation │ ├── usage │ └── ... └── 💻 代码文件
🔮 下篇预告 & 思考题
下篇预告：《团队协作：像乐队一样演奏》
文档写好了，一个人开发太孤单？下一篇我们学 团队协作——邀请朋友加入你的知识星球，分工合作，像乐队一样默契配合。 你将学到：
- 如何添加协作者、分配权限
- 团队分支策略：谁在哪条分支上做什么
- 避免冲突的沟通技巧
今日思考题：
- 如果你要向完全不懂技术的朋友介绍知识星球，你会先让他看 README 还是 Wiki 的哪一页？
- 为什么说“文档不是项目的附属品，而是产品的一部分”？
动手小任务：
- 在你的仓库开启 Wiki
- 至少创建 3 个页面： "home"、 "installation"、 "usage-basic"
- 在 README 末尾加上指向 Wiki 的链接
- 邀请一位朋友（或自己的小号）试着阅读你的 Wiki，提一个修改建议。
📖 延伸资源
- Markdown 进阶语法：表格、流程图、Mermaid 图表
- 优秀的开源项目 Wiki 范例：
- Vue.js、React、VS Code 的 GitHub Wiki
- 文档即代码（Docs as Code）理念：把文档和代码放在一起管理
代码只能告诉机器怎么做，文档才能告诉人类为什么。 好的文档让你的项目从“能用”变成“好用”，从“个人玩具”变成“可分享的作品”。 下一节，我们邀请伙伴加入，让知识星球不再孤单 🎸
