一个文件搞定文档站?Docsify 真的做到了!

它叫 Docsify，在 GitHub 上拿到了 3.1 万+ Star，用 JavaScript 写成，MIT 协议开源。它的核心思路就一句话：不构建，运行时把 Markdown 渲染成网站。

Docsify 到底是什么

传统的文档站点生成器，比如 VuePress、GitBook、MkDocs，都要走一遍构建流程：你写 Markdown，工具把它们编译成一堆静态 HTML，再把这些 HTML 部署到服务器。Docsify 反其道而行之，它只需要一个 index.html 入口文件，剩下的全是 Markdown。用户访问页面时，浏览器端的 JavaScript 按需拉取对应的 .md 文件，当场解析渲染成 HTML。

这意味着你的仓库里只有 Markdown 源文件，没有 dist 目录，没有构建产物，提交记录干净，部署也简单。GitHub Pages、Vercel、Netlify、任意一个静态服务器，甚至你本地用 Python 起个 HTTP 服务，都能直接跑。

为什么值得用

### 无需构建，改完即生效

写文档最烦的就是构建这一步。你改了一个错别字，要重新生成站点；你加了一个新页面，要重新跑命令。Docsify 把这一步省掉了。你直接提交 Markdown，刷新浏览器就能看到最新内容。对于持续迭代的项目文档，这省去了大量重复劳动，也避免了构建失败导致的部署中断。

### 运行时渲染，体积轻

因为不需要预编译 HTML，Docsify 本身非常轻量。核心就是一个 JavaScript 文件加一个 CSS 主题，通过 CDN 引入即可。浏览器拿到 Markdown 后在本地完成解析和渲染，首屏之外的内容按需加载，不会一次性把所有页面都塞给用户。

### 单文件配置，上手门槛低

所有配置都写在 index.html 里的 window.$docsify 对象中。想开启侧边栏，加一个 loadSidebar: true；想换主题，改一行 CSS 链接；想加 GitHub 仓库链接，写一个 repo 字段。没有复杂的配置文件体系，也没有插件系统的黑魔法，看一眼官方文档就能配出一个像模像样的站点。

### 插件生态丰富

Docsify 提供了插件 API，社区围绕它做了不少实用插件。全文搜索插件 docsify-copy-code、代码复制插件、分页插件、字数统计插件、谷歌分析插件，基本都能开箱即用。如果官方插件满足不了需求，你也可以基于插件 API 自己写一个，逻辑就是钩子函数的组合。

### 多主题与封面页

内置了 vue、buble、dark 等多套主题，换主题就是换一行 CSS 链接。还支持封面页（coverpage），在 index.html 里开启后，访问根路径会先展示一个带项目名称、描述和按钮的封面，适合对外展示的项目。

五分钟上手实战

下面用最小可运行示例带你走一遍。不需要 npm，不需要构建工具，只需要两个文件。

### 第一步：创建 index.html

新建一个目录，比如 my-docs，在里面放一个 index.html：

<!DOCTYPE html> <html>   <head>     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />     <meta name="viewport" content="width=device-width,initial-scale=1" />     <meta charset="UTF-8" />     <link       rel="stylesheet"       href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css"     />   </head>   <body>     <div id="app">加载中...</div>     <script>       window.$docsify = {         name: '我的项目文档',         repo: 'your-name/your-repo',         maxLevel: 3,       };     </script>     <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>   </body> </html>

这就是全部。CDN 用 @4 锁定主版本号，会自动拿到最新的次版本和补丁版本，保证拿到 bug 修复又不会有破坏性更新。name 是站点名称，repo 会在右上角生成一个 GitHub 角标链接，maxLevel 控制目录展开到几级标题。

### 第二步：写 README.md

同一个目录下放一个 README.md，它就是站点的首页：

# 我的项目  这是一个演示 Docsify 的示例项目。  ## 特性  - 无需构建 - 运行时渲染 - 单文件配置  ## 快速开始  克隆仓库后，用任意静态服务器打开目录即可。

### 第三步：本地预览

没有 Node 环境也没关系，用 Python 起一个静态服务：

cd my-docs python -m http.server 3000

浏览器打开 http://localhost:3000，你就能看到刚才写的 README 被渲染成了带导航、带目录、带主题的文档站。改 README 保存，刷新页面立即生效。

如果你习惯用 npm，也可以安装官方 CLI 来初始化和预览：

npm i docsify-cli -g docsify init ./docs docsify serve docs

init 命令会帮你生成 index.html、README.md 和 .nojekyll 三个文件，其中 .nojekyll 是给 GitHub Pages 用的，防止它忽略下划线开头的文件。

进阶一：加上侧边栏

只有首页还不够，文档一多就需要侧边栏导航。开启方式分两步。

先在 index.html 里打开配置：

<script>   window.$docsify = {     loadSidebar: true,     subMaxLevel: 2,   }; </script>

再在同目录创建 _sidebar.md：

* [首页](/) * [快速开始](quickstart.md) * [使用指南](guide.md) * [常见问题](faq.md)

subMaxLevel: 2 表示在侧边栏里自动展开每个页面的二级标题作为目录，读者可以直接跳转。新建的 quickstart.md、guide.md 等文件会对应路由 /#/quickstart、/#/guide，无需额外配置。

如果部署到 GitHub Pages，记得在 docs 目录放一个空的 .nojekyll 文件，否则 _sidebar.md 这类下划线开头的文件会被 GitHub Pages 的 Jekyll 忽略。

进阶二：接一个搜索插件

文档内容多了之后，搜索是刚需。Docsify 的全文搜索插件是官方维护的，引入即用。

在 index.html 里，在主脚本之后加上搜索插件的 CDN：

<script src="//cdn.jsdelivr.net/npm/docsify@4"></script> <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>

然后在配置里启用：

<script>   window.$docsify = {     search: {       maxAge: 86400000,       paths: 'auto',       placeholder: '搜索',       noData: '没有结果',       depth: 3,     },   }; </script>

paths: 'auto' 表示自动索引所有 Markdown 文件，depth: 3 控制索引到三级标题。保存刷新，左上角就会出现搜索框，输入关键词能模糊匹配标题和正文。

除了搜索，常用的还有 docsify-copy-code（给代码块加复制按钮）、docsify-pagination（上一页下一页）、docsify-tabs（标签页组件），引入方式一模一样，都是加一个 script 标签再写几行配置。

适合谁用

Docsify 最适合这几类场景：一是开源项目的文档站，尤其是中小规模项目，不想在构建流程上花太多精力；二是个人技术博客或知识库，内容以 Markdown 为主，追求简洁；三是团队内部的产品文档或 API 文档，需要快速上线、频繁更新。

如果你的文档对 SEO 要求极高（因为运行时渲染，搜索引擎抓取的内容不如静态 HTML 完整），或者需要高度定制的页面布局和交互，那 VuePress、Next.js 这类带构建的方案可能更合适。但如果你的核心诉求是写 Markdown、零配置、快速上线，Docsify 几乎是当前最轻的选择。

Docsify 已经在 GitHub 上积累了 3.1 万+ Star，社区活跃，长期维护。感兴趣可以去官方仓库 docsifyjs/docsify 看看，也可以直接访问 docsify.js.org 浏览完整文档。从一个 index.html 开始，你大概十分钟就能拥有自己的文档站。