被文档工具折磨的你，需要喘口气
你是否也有过这样的经历？
兴冲冲写了几十篇技术文档，想搭个团队知识库。
打开GitBook，一顿配置猛如虎，最后卡在编译报错上；
换用VuePress，光是搭环境就折腾一下午，改个错别字还得重新build。
明明是写文档，怎么搞得像在做工程部署？
说实话，我有时候就在想，能不能有个东西，写完Markdown往那一放，刷新下浏览器就能看？
不需要编译、不需要构建、甚至连命令行都不用开几次？
这就是我第一次遇到docsify时的感受——原来写文档可以这么轻。
🎯 本文能帮你解决什么
如果你也在找一款「开箱即用、维护省心、长得还不错」的文档工具，这篇文章就是为你准备的。
我会用最直白的方式，告诉你 docsify 好在哪、怎么装、怎么配，以及那几个我踩过的坑，帮你一天之内从零搭建出一个像样的文档站点。
👩💻我是爱折腾的一名程序媛，喜欢研究全栈开发的各种实践，热爱分享踩坑后的收获与思考，也享受用代码写出各种实用小工具解决问题的快乐。
如果你也在技术这条路上向前走，关注我，愿我们能彼此陪伴，一起成为更好的自己🌱
🧭 主要内容脉络
🔹 一个让人崩溃的文档维护故事
🔹 docsify 到底是什么，它和 GitBook、VuePress 有什么不一样
🔹 从安装到发布，一条龙实战步骤
🔹 那些配置最实用，哪些坑最容易踩
🔹 什么时候该选它，什么时候该换别的
💡 一个让人崩溃的文档维护故事
之前的项目文档库，大都是需要编译的框架。
Node 版本不对，编译报错；依赖装不上，又报错；好不容易 build 成功，部署上去发现样式丢了。
很多次真的想把电脑合上去喝杯奶茶冷静一下。
很多文档工具的定位越来越偏向「网站生成器」，功能是强大了，但写文档这件事本身的体验反而被忽视了。
docsify 的设计哲学不太一样——它不生成静态 HTML，而是运行时直接把 Markdown 转成网页。这意味着你不用编译，写完就能看。
是不是以为这样性能会很差？其实还好，现代浏览器解析那点 JS 根本不算事儿，首屏加载体验完全够用。
🛠️ docsify 到底是个啥
打个生活化的比方：
GitBook 和 VuePress 像是你要装修房子，先画图纸、买材料、施工、验收，最后才能住进去。
docsify 则更像是搭帐篷，把架子撑起来，东西往里一放，立刻就能用。
它的核心原理很简单：
🔹 你写一堆 Markdown 文件放在项目里
🔹 一个 HTML 入口文件引入 docsify 的 JS 和 CSS
🔹 用户访问时，JS 动态拉取对应的 Markdown 并渲染成网页
这里面有个关键的文件_sidebar.md，你只需要在里面列出文档标题和链接，侧边栏就自动生成了。
没有编译步骤，没有复杂的配置，改完文档提交代码就完事。
🚀 一条龙实战步骤
好，咱们直接动手。全程只需要三步，比泡一碗泡面还省事。
📦 第一步：全局安装 docsify-cli
npm i docsify-cli -g
装完后，你就能用docsify命令了。这里有一点要特别注意，如果你公司网络不好，npm 装全局包容易卡住，记得提前切好镜像源，不然第一关就劝退了。
🏗️ 第二步：初始化项目
docsify init ./docs
这个命令会在docs目录下生成三个文件：
🔹index.html—— 入口文件，整个站点就靠它
🔹README.md—— 首页内容，你想展示啥就写啥
🔹.nojekyll—— 防止 GitHub Pages 忽略下划线开头的文件
接下来重点来了，你需要在index.html里加一个配置，开启侧边栏功能：
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 2
}
</script>
然后新建一个_sidebar.md，里面写上你的文档目录结构。比如：
- [首页](/)
- [快速上手](quickstart.md)
- [API 文档](api.md)
- [用户模块](api-user.md)
- [订单模块](api-order.md)
保存，刷新浏览器，侧边栏就出来了。就这么简单。
👀 第三步：本地预览
docsify serve docs
打开http://localhost:3000，你的文档网站就活生生摆在那了。改一个字保存，浏览器自动刷新，体验丝滑。
有一点提醒一下：
就是如果你没装node环境，或者不想安装模块，也可以很简单：
上面的命令行工具做的事，其实就是帮你生成那三个文件，我们自己手动建就好了，index.html里面把css和js引入进来
还有一个就是拉起服务这块，测试的时候直接用VS Code里的Live Server就好，线上就Nginx或IIS了，
再不行就用python -m http.server 3000也一样能起服务
⚠️ 常用配置与容易翻车的点
再说几个我实际项目里觉得最实用的配置。
侧边栏折叠
如果文档层级深，建议开启折叠，不然侧边栏长得能拉好几屏。
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 2,
sidebarDisplayLevel: 1
}
</script>
全文搜索
docsify 内置了搜索插件，只需加一行：