Docsify 搭建 Markdown 知识库本地写文档用 cpolar 临时分享给同事评审文档最怕两件事一是散在聊天记录里二是写完没人愿意看。我的做法很简单把项目说明、接口约定、部署手册都放进一个 Markdown 目录用 Docsify 本地预览再用 cpolar 开一个临时 HTTPS 地址丢给同事评审。这套方案不需要先买服务器也不用为了半小时评审去配置一整套发布流水线。覆盖项目早期、内部评审、客户临时预览、移动端查看效果这几类场景。1 什么是 Docsify这篇里它负责把 Markdown 变成文档站Docsify 是一个文档站生成工具它和常见静态站生成器的区别在于它不会提前把 Markdown 编译成一堆 HTML 文件而是在浏览器里动态渲染 Markdown。这篇教程里我们只拿它做一件事把本地docs目录变成一个可以搜索、有侧边栏、能在浏览器里看的知识库。可以放进去的内容包括项目 README 和快速开始接口说明、字段约定、错误码部署手册、排错记录团队规范、交接文档别一上来就把它当成公司级知识平台。先从一个项目目录开始跑通后面再决定要不要接 GitHub Pages、对象存储或者内部服务器。2 环境准备安装 Node.js、Docsify CLI 和 cpolar这一节先把工具装好。Docsify 负责本地文档站cpolar 负责把本机的3000端口临时映射成外网 HTTPS 地址。2.1 检查 Node.js 和 npmDocsify CLI 通过 npm 安装所以本机要先有 Node.js。打开终端执行node -v npm -v能看到版本号就继续。这里使用 Node.js LTS 版本更稳后面团队成员复现时也更稳。如果本机还没装 Node.js可以去 Node.js 官网下载安装包或者在 macOS 上用 Homebrew 安装brew install node2.2 安装 docsify-cliDocsify 官方快速开始采用全局安装docsify-cli它用来初始化目录和本地预览。npm i docsify-cli -g装完后检查命令是否可用docsify -v如果提示找不到docsify先检查 npm 全局 bin 目录是否在PATH里。这个坑很常见尤其是用 nvm 管 Node.js 的机器。2.3 安装 cpolarcpolar 这一步不是为了正式上线而是为了临时评审。Docsify 默认跑在本机办公室外的同事打不开评审窗口期打开隧道评审结束关闭隧道节奏会轻很多。macOS 可以用 Homebrew 安装brew tap probezy/core brew install cpolar sudo cpolar service install sudo cpolar service startLinux 可以使用官方一键脚本curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash安装后打开本地管理页面open http://127.0.0.1:9200Linux 桌面环境没有open命令时直接在浏览器访问http://127.0.0.1:9200。登录后 cpolar 会在本机建立账号绑定纯命令行环境也可以用cpolar authtoken手动绑定。3 初始化 Docsify创建知识库目录这里我用team-docs-demo做示例项目名。你可以换成自己的项目目录但后面的命令要保持一致。mkdir team-docs-demo cd team-docs-demo docsify init ./docs初始化完成后目录里会有这些文件tree -a docs典型结构是docs ├── .nojekyll ├── README.md └── index.htmlREADME.md是首页内容index.html是 Docsify 的入口文件.nojekyll用在 GitHub Pages 场景保留即可。先改一下首页内容确认渲染链路正常cat docs/README.md EOF # 团队知识库 这里记录项目文档、接口约定、部署步骤和排错经验。 ## 快速入口 - [接口说明](api.md) - [部署手册](deploy.md) - [排错记录](troubleshooting.md) EOF再补三个页面cat docs/api.md EOF # 接口说明 ## 用户列表 请求地址GET /api/users 响应示例 json { items: [], total: 0 }EOFcat docs/deploy.md EOF部署手册启动服务npm install npm run build npm run startEOFcat docs/troubleshooting.md EOF排错记录本地端口被占用查看 3000 端口占用lsof -i :3000EOF这里别急着写一大堆文档。先放 3 个短页面跑通侧边栏和搜索后再迁移原来的 Markdown。 ## 4 配置侧边栏、导航和搜索 Docsify 的好用之处在于配置很轻。我们加一个侧边栏再开启搜索插件知识库就有了基本可用的阅读体验。 ### 4.1 添加侧边栏 创建 _sidebar.md bash cat docs/_sidebar.md EOF - 项目文档 - [首页](README.md) - [接口说明](api.md) - [部署手册](deploy.md) - [排错记录](troubleshooting.md) EOF再修改docs/index.html把loadSidebar和搜索配置加进去。可以直接覆盖成下面这个版本cat docs/index.html EOF !doctype html html head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title团队知识库/title link relstylesheet href//cdn.jsdelivr.net/npm/docsify5/dist/themes/core.min.css /head body div idapp加载中.../div script window.$docsify { name: 团队知识库, repo: , loadSidebar: true, subMaxLevel: 2, auto2top: true, search: { paths: auto, placeholder: 搜索文档, noData: 没有找到结果, depth: 3 } } /script script src//cdn.jsdelivr.net/npm/docsify5/dist/docsify.min.js/script script src//cdn.jsdelivr.net/npm/docsify5/dist/plugins/search.min.js/script /body /html EOF划重点loadSidebar: true会让 Docsify 读取_sidebar.mdsubMaxLevel: 2会把页面里的二级标题也展示出来。文档多起来以后这两个配置比主题颜色更重要。如果侧边栏没出来优先检查文件名是不是_sidebar.md下划线别漏再检查当前访问路径是否在docs服务根目录下。4.2 本地启动预览在项目根目录执行docsify serve docs终端会显示本地访问地址默认是http://localhost:3000打开浏览器访问http://localhost:3000能看到首页、侧边栏和搜索框就说明知识库已经跑起来了。这一步不是为了截图好看而是确认 Markdown 到浏览器的链路通了。后面你改README.md、api.md这些文件浏览器刷新就能看到新内容。5 用 cpolar 暴露本地 3000 端口生成临时 HTTPS 地址本地能看只是第一步。真正评审时经常会遇到一个尴尬点同事不在同一个网络客户也无法访问你的localhost:3000。这时候就用 cpolar 开一个 HTTP 隧道把本地 Docsify 服务临时映射出去。保持docsify serve docs运行再开一个新的终端执行cpolar http 3000命令运行后终端会输出公网访问地址。你也可以打开 cpolar 管理页面查看http://127.0.0.1:9200在“状态 / 在线隧道列表”里找到 HTTP 隧道复制 HTTPS 地址发给同事。对方打开这个地址看到的就是你本机正在运行的 Docsify 文档站。免费随机地址用于临时演示地址会在 24 小时内变化。评审、验收、移动端预览这类短窗口任务足够用了如果团队要长期固定访问再考虑固定二级子域名或正式部署方案。这里有个安全提醒不要把含密钥、生产数据库地址、客户隐私的文档放进临时评审站。Docsify 是文档展示工具不负责替你做内容脱敏。6 同事评审时怎么更新文档、排错和关闭隧道评审时最舒服的流程是你本地改 Markdown同事刷新页面看结果。比起来回发压缩包这种方式省很多沟通成本。6.1 修改文档后刷新即可比如你要改部署手册cat docs/deploy.md EOF ## 检查服务状态 bash curl http://127.0.0.1:3000EOF保存后让同事刷新 cpolar 的 HTTPS 地址。Docsify 会重新加载 Markdown 内容。 如果同事说页面没变先让对方强制刷新浏览器再确认你改的是 docs 目录下的文件不是项目里另一个同名 Markdown。 ### 6.2 手机预览也要看一眼 Docsify 的页面在手机上也能阅读。把 cpolar 的 HTTPS 地址发到手机浏览器里看首页、侧边栏、搜索框是否顺手。 这一步很实用。很多接口文档在电脑上看着清楚到了手机上标题层级太深、表格太宽评审时很快就暴露出来。 ### 6.3 评审结束后关闭 如果你是用命令行开的临时隧道在运行 cpolar http 3000 的终端里按 Ctrl C 即可关闭。 Docsify 本地服务也可以按 Ctrl C 关闭。确认两个终端都停掉后外部链接就不再提供这次预览。 如果使用 cpolar Web UI 创建了隧道就到隧道列表里停止或删除对应隧道。这里别偷懒临时评审链接用完就关是很好的团队习惯。 ## 7 常见问题这几个点最容易卡住 ### 7.1 端口 3000 被占用 Docsify 默认用 3000如果端口被别的服务占了可以指定其他端口 bash docsify serve docs -p 3001对应的 cpolar 命令也要改成同一个端口cpolar http 3001端口前后一致很关键。Docsify 跑在3001cpolar 却映射3000外部访问就会打开错误服务或直接失败。7.2 图片路径显示不出来Markdown 图片统一放在docs/assets/目录下例如mkdir -p docs/assets引用时使用相对路径图片不显示时先检查文件名大小写。macOS 本地不敏感Linux 或部署环境里会卡得很明显。7.3 搜索不到新页面搜索插件会根据侧边栏和已访问页面建立索引。新页面加完后记得把它写进_sidebar.md再刷新页面。如果搜索框没有出现检查index.html里是否同时保留了search配置和search.min.js插件脚本。7.4 cpolar 地址打不开按这个顺序查本机http://localhost:3000是否能打开 Docsifycpolar 管理页http://127.0.0.1:9200是否能打开在线隧道列表里 HTTP 隧道是否在线复制给同事的是 HTTPS 地址不是本地地址排错时别一上来重装。先确认本地服务通再看隧道状态能省不少时间。8 总结到这里我们已经把一个普通 Markdown 目录做成了 Docsify 文档站本地可以写、浏览器可以预览、侧边栏和搜索也能用需要外部评审时再用 cpolar 临时开放一个 HTTPS 地址给同事访问。关键步骤就三件事用docsify init ./docs初始化文档目录再用docsify serve docs本地预览。配置_sidebar.md、loadSidebar和搜索插件让知识库具备基本导航能力。用cpolar http 3000暴露本地 Docsify 服务评审结束后及时关闭隧道。我把这套流程定位成“文档评审工作流”而不是一套正式发布系统。它的优势在于轻Markdown 继续放在项目里评审链接按需打开问题改完马上刷新。等文档稳定下来再迁移到 GitHub Pages、内部服务器或团队知识平台会顺手很多。
)
