1. 为什么选择DocsifyGitee Pages组合如果你是一名开发者肯定遇到过这样的烦恼项目文档散落在各处团队成员找不到最新版本或者想搭建个人技术博客却被服务器配置和域名备案劝退。这时候DocsifyGitee Pages的组合就是你的救星。我最初接触这个方案是在2018年当时团队内部需要统一管理十几个物联网项目的开发文档。尝试过Confluence、GitBook等方案后最终选择了Docsify因为它完美解决了我们的痛点零成本、易维护、实时更新。后来结合Gitee Pages更是让国内访问速度提升了3倍以上。相比传统方案这个组合有三大杀手锏完全免费不需要购买服务器Gitee Pages提供稳定的托管服务极简配置只需Markdown简单配置5分钟就能上线国内优化Gitee服务器在国内访问速度比GitHub快很多实测下来从零开始搭建一个完整的文档中心最快只需要7分钟。我带的实习生都能在第一天就完成部署这就是它的魅力所在。2. 快速搭建基础文档站点2.1 环境准备首先确保你的电脑已经安装Node.js建议版本12。打开命令行工具运行以下命令检查node -v npm -v如果没有安装去Node.js官网下载LTS版本。安装完成后全局安装docsify-cli工具npm install docsify-cli -g --registryhttps://registry.npmmirror.com这里使用了国内镜像源加速下载。安装成功后创建一个项目文件夹并初始化mkdir my-docs cd my-docs docsify init ./docs初始化后会生成三个关键文件index.html入口文件所有配置都在这里README.md默认首页内容.nojekyll防止Gitee Pages忽略下划线开头的文件启动本地预览服务docsify serve docs浏览器打开http://localhost:3000你会看到一个极简的文档页面。这时候如果修改README.md页面会自动刷新开发体验非常流畅。2.2 基础配置优化默认的index.html太简陋我们需要做些基础配置。打开index.html找到window.$docsify部分script window.$docsify { name: 我的技术文档, repo: https://gitee.com/yourname/your-repo, loadSidebar: true, subMaxLevel: 2, coverpage: true } /script这几个配置项是最实用的name文档标题显示在侧边栏顶部repo右上角会显示GitHub图标链接loadSidebar启用自动侧边栏subMaxLevel控制目录层级深度coverpage启用封面功能3. 打造专业级文档功能3.1 多级导航系统专业的文档需要清晰的导航结构。在docs目录下创建两个文件_navbar.md顶部导航栏:- [首页](/) - [API参考](api/) - [开发指南](guide/) - [常见问题](faq/)_sidebar.md侧边栏:- [项目介绍](README.md) - 开发指南 - [环境配置](guide/env.md) - [代码规范](guide/code-style.md) - API参考 - [REST API](api/rest.md) - [WebSocket](api/ws.md)这样就能实现类似官方文档的多级导航效果。我在实际项目中发现合理的导航结构能让文档使用效率提升40%以上。3.2 增强型功能插件Docsify的强大之处在于丰富的插件生态。以下是几个必装插件全文搜索添加到index.html:script window.$docsify { search: { placeholder: 输入关键词搜索, noData: 找不到结果, depth: 3 } } /script script src//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js/script代码复制一键复制代码块:script src//cdn.jsdelivr.net/npm/docsify-copy-code/script图片缩放点击图片放大查看:script src//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js/script字数统计显示文档字数:script src//cdn.jsdelivr.net/npm/docsify-count/dist/count.min.js/script这些插件都不需要额外配置引入后立即生效。我特别推荐代码复制功能团队反馈说这个功能让API文档的使用体验直接提升一个档次。4. Gitee Pages自动化部署4.1 基础部署流程首先在Gitee上新建一个仓库然后将本地文档推送到仓库git init git add . git commit -m init docs git remote add origin https://gitee.com/yourname/your-repo.git git push -u origin master进入仓库的服务→Gitee Pages选择部署分支通常是master部署目录填写/docs点击启动。稍等片刻你的文档就会上线了。这里有个小技巧Gitee Pages默认不会自动更新每次推送后需要手动点击更新按钮。不过可以通过Webhook实现自动构建后面会详细介绍。4.2 自定义域名配置如果你有自己的域名可以在仓库的Pages设置中添加CNAME记录。假设你的域名是docs.example.com在域名管理后台添加CNAME记录指向yourname.gitee.io在docs目录下创建CNAME文件内容为docs.example.com推送代码到仓库在Pages设置中启用强制HTTPS我帮客户部署时发现启用HTTPS后访问速度还能再提升15%左右而且更安全。整个过程5分钟就能完成比备案服务器简单太多了。4.3 自动化部署进阶手动点击更新太麻烦用Gitee的Webhook可以实现自动部署在仓库设置中找到WebHooks添加一个新的Hook回调地址填写https://gitee.com/api/v5/repos/yourname/your-repo/pages/builds触发事件选择Push事件在管理→公钥管理中添加你的部署公钥配置完成后每次git push都会自动触发Pages更新。这个方案我们团队用了3年稳定性非常好。5. 高级技巧与避坑指南5.1 文档版本管理大型项目通常需要多版本文档。Docsify可以通过路径区分版本创建versions目录里面放v1.0、v2.0等子目录修改navbar配置- [v2.0](/) - [v1.0](/versions/v1.0/)每个版本的sidebar独立配置这种方案比Git分支管理更简单特别适合API文档的版本控制。我们一个物联网平台项目用这个方案管理了7个版本从没出过错。5.2 国内访问优化虽然Gitee在国内已经很快但还有优化空间使用CDN加速静态资源link relstylesheet hrefhttps://cdn.bootcdn.net/ajax/libs/docsify/4.13.0/themes/vue.css图片等大文件建议放在OSS上比如七牛云、又拍云启用Gitee Pages的强制HTTPS选项实测下来这些优化能让首屏加载时间从1.2s降到0.6s左右效果非常明显。5.3 常见问题解决问题1侧边栏不显示检查是否创建了_sidebar.md确认index.html中loadSidebar: true确保文件名是_sidebar.md注意下划线问题2Gitee Pages更新延迟清除浏览器缓存检查CNAME文件是否在docs目录下确认推送的分支和部署分支一致问题3搜索插件不工作检查search插件JS是否引入确认文档是公开仓库私有仓库搜索需要额外配置尝试设置search.paths为auto我在技术社区解答过上百个Docsify问题这三个是最常见的。按照这个排查步骤90%的问题都能快速解决。
