企业官网建设流程全解析

文档整理这件事，我算是栽过跟头的。几年前维护一个开源小项目，README越写越长，从“快速上手”一路写到“常见问题”，最后光是一个页面就三百多行，读者翻到API参数时已经在骂人。后来我把文档整体搬进了gitbook，才真正体会到什么叫“写文档不挨骂”。这篇文章不做泛泛的软件介绍，只讲我实际把项目文档从README迁移到gitbook的全过程，包括为什么放弃自建博客、如何设计目录、怎么和GitHub联动更新，以及踩过的几个具体坑。如果你正在纠结团队文档应该用什么工具，或者想把仓库里的Markdown变成一本像样的在线手册，这篇应该能省你不少时间。

1. 为什么我最终把项目文档搬到了GitBook

1.1 从README单页文档到维护噩梦

我一开始和大家一样，觉得项目文档就是README，顶多再加一个docs目录放几篇进阶说明。这个模式在小项目阶段非常舒服：改一个文件、提交一次代码，问题就解决了。可当项目跑到八九千行，功能模块从两三个变成十来个之后，问题开始成片出现。首先是README单页巨长，人在浏览器里滚动三次都看不到底；其次是检索困难，读者问我某个配置项在哪，我也得打开编辑器全文搜；更麻烦的是协作，团队四个仓库同时维护，每个人都往同一个docs目录塞自己的文件，目录结构很快就失控了。

这其实是很典型的“文档资产化”问题：当文档数量超过某个阈值，它就不能再按普通代码文件来管理了。你需要目录、索引、版本、全文搜索和相对清晰的发布流程。传统做法是自己搭一个博客或者Wiki，但博客的写作重心是文章而不是SDK手册，Wiki的组织成本又过高，维护起来比写代码还累。我甚至试过直接用静态站点生成器，把Markdown渲染成页面，但因为每次都要处理主题、部署和页面路由，整个团队的写作门槛被拉高了，最后还是没坚持下来。

真正让我下决心换方案，是一次很具体的场景：有用户提Issue说“看完快速开始，还是不知道第二个参数该传什么”。我打开文档检查，发现他说的这个接口散落在三个不同的页面里，要凑齐完整用法至少要点五次侧边栏。这时候我意识到，问题已经不是某个段落写得不好，而是整个文档缺少一个统一的组织框架。

1.2 GitBook给团队带来的实际改变

GitBook给我的第一印象是“它把文档这件事收敛成了一棵树”。目录结构用SUMMARY.md管理，同一棵树下组织所有页面；页面之间用相对链接跳转；整个文档作为一步git仓库的历史演进，每次改动都有提交记录。对接GitHub之后，仓库推上去，文档站自动更新，完全没有维护服务器和后台数据库的成本。团队成员写文档，不需要学习任何后台操作，只要像写代码一样改Markdown文件，剩下的交给工具，这就极大降低了参与门槛。

我迁移完成后的变化非常直观：侧边栏有了清晰层级，全局搜索能直接定位文字，API页面独立成章，不再和教程混在一起。社区里的新贡献者开始主动改文档了，因为他们知道改一处Markdown、提一个PR，几分钟就能在线上看到效果。这个反馈闭环很重要，如果文档更新流程很重，大多数人会在第一步就放弃。GitBook的GitHub集成恰好把这个闭环压缩到最短。

当然，GitBook并不是万能的。自定义程度、强交互的组件、复杂权限管理，它都不算最灵活。但对“一个开源项目的中型文档站”这个场景，它几乎是性价比最高的选项：免费方案够用，Markdown生态成熟，托管稳定，搜索引擎收录也正常，不存在需要额外运维的隐患。后面我会细讲这些边界条件，免得你误判。

1.3 和同类工具的取舍对比

选型的时候我对比过几类工具，这里直接放结论。如果你追求极致的静态站控制和性能，Docusaurus和VuePress都是好选择；如果团队熟悉Python，MkDocs配Material主题也很顺；如果你想要“开箱即用、连接GitHub就能发布”，GitBook在这条路上做得最省心。

再说一个很多人忽略的细节：GitBook的在线编辑器也能直接改页面并提交到GitHub，这意味着非技术成员（比如产品、运营）也能参与文档维护。你只要给他们在仓库里开一个分支权限，他们就能在网页上改文字、提PR，不需要在本机装任何工具。这个能力在我实际推进文档规范时帮了很大的忙，因为很多文档问题不是没人写，而是写作环境离使用者太远。

2. 初始化并托管第一本“书”

2.1 两种主流玩法，官方托管和本地构建怎么选

想用GitBook，现阶段存在两条路。一条是直接用官方托管平台，在GitBook网站上创建Space，连接你的GitHub仓库，它会自动读取仓库里的文档内容并构建发布，地址形如“你的名字.gitbook.io/项目名”。另一条是网络上有大量历史教程提到的gitbook-cli本地构建方式，在项目目录里执行gitbook init、gitbook serve，把文档构建成静态站后部署到你自己的服务器。前几年官方主推CLI，现在的产品重心在托管平台，所以我建议选官方托管作为主线，理由很简单：维护成本最低，发布链路最短。

如果你是第一次接触，我建议你按这个顺序走：先在GitBook官网注册账号，再关联GitHub账号，然后创建一个新的Space，在创建流程里选择“GitHub”，指定仓库和分支，设置文档目录路径。GitBook会自动扫描目录，根据SUMMARY.md生成侧边栏。整个过程十分钟内就能跑通，比大部分建站工具的部署体验都要省心。至于旧版CLI，我仍然把它当作本地预览的工具来用，方便在提交前检查页面效果，但要提醒一句：旧版命令依赖的运行时版本较老，在新系统上经常会遇到依赖安装问题，能不碰就别硬碰。

2.2 SUMMARY.md：一本书的目录大纲

GitBook的目录组织围绕一个文件：SUMMARY.md。这个文件决定了侧边栏的层级、顺序和分组。最简单的目录结构大概是这样的：

# Summary ## 快速开始 * [介绍](README.md) * [安装](quickstart/install.md) * [第一个示例](quickstart/first-demo.md) ## 使用指南 * [核心概念](guide/concepts.md) * [配置说明](guide/configuration.md) * [接口参考](guide/api.md) ## 运维 * [常见问题](faq.md) * [版本记录](changelog.md)

注意几个容易踩坑的细节：第一，文件名尽量避免中文和空格，统一用短横线连接，比如install-guide.md，否则图片路径和链接在某些环境下容易出问题；第二，SUMMARY.md里的相对路径是相对于该文件所在目录的，目录结构调整时要同步修改，否则会出现404；第三，二级标题表示分组，不会生成可点击的页面，它只是把下面的页面归到一个折叠组里。很多人在刚上手时会以为也要对应一个目录，其实不需要。

另一个经验是：不要一上来就把所有页面都塞进SUMMARY.md。我见过不少仓库，文档总量不到二十页，侧边栏已经有四级嵌套，读者根本不知道从哪儿看起。我建议把主线控制在三级以内，一个分组下面最多挂七八个页面，再多的内容说明你需要拆分专题，而不是继续加层级。

2.3 Markdown与GitBook的兼容性细节

GitBook支持的是CommonMark标准Markdown，外加一些官方扩展。大部分你在GitHub上写README的经验能直接迁移过来，但有几个点值得注意。首先是相对链接，页面A里链接图片或另一个页面，推荐写相对路径，比如./images/first.png，这样在本仓库和其他编辑器里都能预览，不依赖线上域名。其次是HTML片段，基础标签可以渲染，但脚本类、样式类内容多半会被过滤，不要投机取巧。还有表格、任务列表、脚注这类扩展语法，官方基本支持，但如果你用了非常冷门的语法，建议在本地预览时确认一次，别等线上页面出问题再回查。

我在迁移过程中就遇到过一个典型问题：Doc里的图片之前都用外链，迁移后有些图片源站失效，导致线上页面出现大片红叉。后来我统一把图片收进仓库的assets目录，用相对路径引用，问题才彻底解决。这件事给我的教训是，文档里的资源最好和代码同生命周期——仓库就是文档的唯一数据源，一切依赖外部站点的资源都算隐藏风险。你可以在代码评审阶段增加一个约定：凡是新增图片，必须放进本地目录，不放外链，这条规则执行一个月后，文档站的整体稳定性明显提升。

3. 文档内容组织的进阶操作

3.1 结构规划：按用户任务而不是按代码模块划分

很多技术团队组织文档时犯的第一个错误，是按照代码模块来写，比如“过滤器模块”“缓存模块”“消息队列模块”。这个思路对维护代码的人友好，但对使用文档的用户非常不友好。使用者不会说“我想看缓存模块”，他们会说“我想让接口的响应速度快一点”。所以我布置文档结构时，优先按用户任务划分：先给“快速开始”让用户跑通最小示例，再给“核心概念”讲清楚设计思路，然后是“操作指南”按场景归类，最后才是“API参考”作为字典查询。

一个我后来反复推荐的模板长这样：首页负责一句话说明项目是什么、安装命令、一个能跑的Demo；快速开始控制在二十分钟内能读完并操作；核心概念章节讲三到五个关键名词，配图尽量用简单示意；操作指南按“如何做一件事”组织，比如“如何接入登录”“如何配置告警”；API参考单独成组，按模块列参数和返回值。这套结构和开源社区比较流行的Diátaxis文档框架思路接近，能覆盖新手、老手和集成者三类读者。

有人会问：这样组织会不会导致大量的重复内容？确实会。我的处理方式是允许轻微重复，但重复的部分必须措辞一致。比如“安装命令”在快速开始里出现过，那在高级部署页面里就直接引用或者写“参见快速开始”，不要另写一遍。这样即使页面之间内容有交叠，也没有维护成本。真正要避免的是同一概念在不同页面里出现同一件事的两种描述，一旦出现，用户必然困惑。

3.2 引用、锚点和变量：让文档不写重复内容

文档规模起来之后，最讨厌的事情就是“复制粘贴式更新”。你改了一处命令，结果有七个页面里的同一个命令还是旧版，这种问题在传统文档站里几乎无解，但GitBook支持一些机制来缓解，最关键的是善用引用和锚点。引用就是用相对链接跳转到已经存在的章节，比如在“升级指南”里写“请先阅读 安装说明 ”，而不是把安装步骤再抄一遍。这样安装步骤如果有变化，你只需要改一处，升级指南会自动跟着变。

锚点则是为了跳到同一页面的指定小节。GitBook会为标题自动生成锚点，比如页面里有个## 常见错误，就可以用链接指向#常见错误。需要注意的是，中文标题的锚点生成规则在不同版本里并不完全一致，我建议锚点链接尽量用英文标题，或者在使用中文标题时把链接复制到浏览器里实测一次，避免线上跳转无效。

变量功能在官方托管环境里并不像很多模板系统那样开放，网上一些旧教程提到的book.json自定义变量，在新版托管平台上已经不受支持了。我在实际维护中逐渐意识到，与其纠结变量系统，不如用好“单一事实来源”的思路：把会反复修改的数据（比如版本号、下载地址、默认端口）集中放在一个单独的页面里，其他页面用引用指向它。这样变量系统的取代品其实就是“页面引用”，维护成本同样很低。

3.3 提示块、折叠块和团队喜欢的小组件

GitBook官方提供了一些很实用的块级组件，零成本提升页面可读性。最常用的是提示块（hint），格式如下：

{% hint style="info" %} 这里是一条背景说明。 {% endhint %} {% hint style="warning" %} 这里是需要注意的风险提示。 {% endhint %} {% hint style="danger" %} 这里是会出问题的高危操作提醒。 {% endhint %}

对应的渲染效果是带背景色的提示条，有info、warning、danger等样式。我在项目文档里用得最多的是warning，用来标注“版本不兼容”“目录权限”这类问题；danger很少用，因为既然知道是高危操作，就应该在步骤里避免，而不是事后提醒。还有一个很好用的组件是折叠块，适合放日志、完整的配置文件示例，页面默认折叠起来，点击才展开，避免长页面刷屏。

值得一提的还有tabs组件，可以在同一个位置切换不同操作系统的命令，比如Linux、macOS、Windows三种安装方式各占一个Tab。这个组件特别适合做跨平台工具文档。不过要记住，任何组件都只是排版工具，它不能替代清楚的文字表达。我的经验是：一段内容里提示块不要超过两三个，否则页面会变成一块一块的色块，阅读体验反而下降。组件服务于结构，结构永远大于装饰。

4. 发布、自动化与版本管理

4.1 官方GitHub集成：push即发布

官方托管一个很大的卖点就是GitHub集成。你在GitBook后台创建Space并绑定仓库后，仓库每次push到指定分支，GitBook都会自动拉取新的内容并重新构建。这样，文档更新的流程完全复刻了代码发布的流程：本地改文件、提交、push，线上文档在几分钟内更新完毕。整个过程几乎没有中间步骤，也不用写Webhook，因为集成是官方的已经在后台为你配好了。

如果有多个文档站需求，比如项目A和项目B各自需要独立站点，可以在GitBook里分别创建Space，分别连接对应仓库。将来想改绑定的仓库或分支，也可以在Space设置里调整。这个过程我唯一的建议是：团队的提交信息里尽量保持一些可读性，比如docs: 更新安装说明，这样当文档线上出现问题时，你能快速定位是哪一次提交引起的。文档站一旦有历史版本回溯的需求，这个习惯会帮你省下大量时间。

需要留意的是权限问题。连接GitHub时，GitBook需要获得仓库的读写权限，默认会被要求授权。如果你用的是公司组织账号，建议单独为文档仓库建一个机器人账号或使用官方支持的应用权限，不要把一个核心维护者的个人账号绑定在自动化流程里。这个细节在个人项目里无所谓，在团队项目中早晚会遇到。

4.2 发版时自动更新文档的脚本化操作

文档最怕的一件事是版本号不一致。代码已经发到v2.1.0，文档页面里的版本号还停在v2.0.0，这在真实项目中太常见了。我从那次被用户提醒“文档版本写错了”之后，就在发版脚本里加了一段自动更新文档的步骤。思路很简单：发版脚本修改完代码版本号之后，同时把文档里的版本号一并更新并提交，再统一推送到GitBook绑定的分支上。

一个缩略的脚本示例是这样的：

#!/bin/bash # 用法: ./release.sh 2.1.0 VERSION=$1 # 更新代码版本 sed -i "s/version = .*/version = \"$VERSION\"/" src/version.go # 更新文档版本 sed -i "s/当前版本：.*/当前版本：v$VERSION/" docs/README.md # 提交并推送，触发 GitBook 自动更新 git add -A git commit -m "release: v$VERSION，同步更新文档" git push origin main

这段脚本看起来简单，但它解决了两个核心问题：第一，版本号被强制收敛到一个发布流程里，不会出现手工遗漏；第二，文档更新和代码发版绑定在同一次提交里，回溯历史时一条提交就能看到所有变更。脚本里的sed命令替换格式要根据你的文档实际文案调整，但整体思路是通用的。

我还做过一个更激进的做法：在CI流水线里加一步“构建成功后，自动把生成的示例配置写入文档”，这样文档里的配置永远来自当前代码的真实输出，永远不会编造。不过这种方案对仓库结构要求比较高，适合项目已经比较规范之后再引入。如果你想做，建议先从一个文件开始试点，不要一下全面铺开，否则CI失败率会上升。

4.3 多分支对应多版本，旧版文档也有人管

文档和代码一样，会面临多版本问题。我维护的项目发布过v1.x和v2.x，两者之间API差异不小。如果文档站只保留最新版本，用旧版本的用户就会很痛苦；如果只保留旧版本，新用户又看不到新功能。GitBook对这个问题并没有一个专门的黑科技按钮，它最朴素的解法是：同一个仓库的不同分支，对应不同的Space。

我在仓库里维护了两个长期分支：main对应最新文档，v1.x-stable对应旧版文档。每次发版，我会把当前版本的内容同步到对应分支，并确保分支里的“当前版本”标签指向正确。用户在文档站的侧边栏里能看到两个入口，分别标注latest和v1.x。这个方案的成本不高，关键是你要提前定好分支策略，并且在发版流程里固化成操作清单，否则很容易出现“该不该更新旧分支”的犹豫。

版本管理还有一个容易被忽略的维度：文档里提到的依赖版本。比如项目v2.x依赖某个基础库，旧版v1.x依赖的是另一个版本，如果文档里只写“请安装最新版基础库”，旧版用户就会踩坑。我现在的写法是把依赖版本也放进对应分支的文档里，同时用提示块标注“本页面向v1.x”。文档的版本归属要写在页面的元信息或开头，而不是藏在某段正文里，这样读者一眼就知道自己看的是哪个版本的说明。

5. 折腾过的坑和值得留存的技巧

5.1 图片路径、中文文件名和构建超时

先说图片。我在本地编辑Markdown时，图片都是好的，可一旦推送到GitBook，有时候图片会裂开。排查下来，绝大多数原因都是路径写法的问题。GitBook官方托管对仓库内图片的处理和本地预览器默认逻辑不太一样，尤其是Windows路径符号和带空格的文件夹名，都很容易触发解析异常。我的解决方案是：图片全部放到docs/assets目录，文件名只用字母、数字和短横线，引用时使用相对路径，彻底杜绝这类问题。

另一个让我印象深刻的坑是中文文件名。我最初为了SEO，给很多页面起了中文文件名，处理器对中文路径的支持时好时坏，最后只好全部改成英文文件名，标题再在页面内部用Markdown标题展示中文。还有一次，团队一个分支里的图片目录塞了几百张高清截图，导致官方构建超时，页面长时间不更新。这件事让我意识到，文档仓库也要控制资产体积，上传图片前先压缩，尽量用WebP格式，超过1MB的截图基本都有压缩空间。我的经验是：文档仓库的构建时间最好控制在两分钟以内，一旦超过，发布体验就会明显下滑。

5.2 排版细节：同一本书，排得好不好差距很大

同样一份内容，排版差异能让阅读效率差出一倍。GitBook虽然无法做到像设计工具那样精细排版，但几个设置点足够把文档调舒服。第一，SUMMARY.md里分组命名要短，最好四个字以内，比如“指南”“部署”“API”；第二，页面标题的层级要克制，一页里最多两个三级的标题层级，过了就拆页；第三，表格列数不要超过六列，否则手机端阅读体验很差，横向滚动会让人崩溃。

代码块的排版也值得单独说。太长的命令行最好拆成多段并加注释，路径用占位符代替具体的用户名，比如/your-project/logs。列表的使用要谨慎，只有当条目确实存在并列关系时才用无序列表，否则用普通段落。另外，提示块里的文字要简短，一两句话能说清楚的问题，不要在提示块里写三段话。排版本质上是替读者降低认知负担，而不是展示作者有多细致，想明白这一点，很多取舍就自然清楚了。

5.3 小团队协作时最实用的几条规矩

最后分享几条我在维护GitBook过程中沉淀下来的团队约定，它们比任何工具配置都管用。第一条，文档改动也必须走PR评审，评审重点不是语法，而是“这句话用户能看懂吗”，这条约定保证了文档质量和代码质量同步。第二条，修复文档问题时，在Issue里关联对应页面链接，方便后续复盘；不要只在新提交里写fix docs，却不说明具体改的哪个页面。第三条，每个新功能合入代码的同时，必须更新对应的文档页面，否则不允许合入，这是我认为最有效的一条硬性规则，能从根本上杜绝功能上线但文档空白的尴尬。

这些约定听起来简单，执行起来却需要耐心。我在团队里推行时，最开始一个月确实会有遗漏，后来我们把“文档是否更新”直接做进了代码评审清单里，每个PR模板里都有一项“文档更新情况”，通过流程约束来替代人的自觉。慢慢地，团队的文档维护就从一个低优先级任务，变成了日常开发的一部分。现在新人入职时，快速开始、核心概念、部署指南这几篇文档基本覆盖了所有高频问题，每天至少能省下不少反复答疑的时间。对我来说，这才是一个文档工具真正的价值所在。