docsify是一个有魔法的文档网站生成器，它能够动态生成您的文档网站。与GitBook、Hexo不同，它不生成静态html文件，而是智能地加载和解析您的md文件，并将其显示为网站。要开始使用它，只需创建一个index.html并将其部署在GitHub Page/Gitee Page等第三方站点上即可。

官网：docsify

特点：

以前曾经折腾过一段时间 hexo 个人静态博客，总体来说还是比较满意的，hexo 也支持md渲染、一键部署、包括很多三方的插件和丰富的拓展性，唯一的不足可能就是相比 docify 配置比较麻烦，两者最大的区别就是当本地文件变更的时，hexo 需要首先通过hexo -c清空目前生成的静态网页文件，然后再通过hexo -g根据本地变更后的新文件构建出一个 public目录存放网站的静态文件，然后如果需要查看效果的话，还需通过hexo -s启动本地的hexo服务，而 Docsify 并不需要构建静态html文件，并且本地文件变更时网站会进行热部署，自动的变更到本地3000端口实时展示，极大的减轻了我们对于网站的管理，能让我们更加专注的进行文档编写或者知识的分享。

安装 docsify 之前，我们需要安装npm包管理器，而安装了node.js就会自动安装npm，对于node.js，直接去Node.js官网选择合适的版本进行下载，然后一键安装即可。

接着我们来全局安装 docsify-cli，这是一个 docsify 的命令行工具，可以帮助我们在本地进行 docsify 的初始化和网站的预览。

然后我们创建一个文件夹，用来存储 docsify 所有的文件，接着输入以下命令进行初始化

可以看到初始化成功了，我们就可以在刚创建的 Docsify 文件夹中查看到README.md和index.html两个文件，此外还存在一个隐藏文件.nojekyll

根据上述提示命令，我们便可启动 docsify 的网站，默认在本地的3000端口

我们访问该网址，便可以看到内容

这里渲染的内容就是上述 Docsify 文件夹中的 README.md，我们如果更改该文件中的内容，网站的内容会自动同步更新。

我们可以轻松的在docsify 实现多级路由的网站，比如在前面创建的 Docsify 文件夹中创建guide.md、zh-cn/READEME.md、zh-cn/guide.md，结构如下所示：

此时我们访问如下url即可以访问到对应的页面：

默认情况下，我们的侧边栏是根据 Markdown 文件自动生成，我们也可以定制化进行设定，首先修改Docsdify/index.html开启侧边栏的选项添加loadSiderbar: true，这样设置后就会加载 Docsify 目录下的 _sidebar.md 文件进行加载而渲染成我们定制的侧边栏。

然后我们在 Docsify 目录下创建一个 _sidebar.md 文件，里面可以对侧边栏进行配置，比如这里配置如下：

也就是 MarkDown 中的超链接语法，后面的路径也就对应着上述多页文档的路由路径

这样设置以后，渲染出的侧边栏如下图所示，我们点击对应地方即可跳转到对应的多页文档

此外我们还可以指定页面的标题，比如这里指定首页的标题为home

:page_facing_up: 补充：嵌套的侧边栏

上述我们是在 Docsify 根目录下新建了一个 _sidebar.md表示网站根路径也就是默认3000端口路径下的侧边栏样式，但是 Docsify 是支持多页文档的，比如上述第3点中我们在根目录下创建了 zh-cn 目录，在这个目录下又有两个文件，我们也可以针对 zh-ch 这个目录对应的路径，定制化该目录下的侧边栏。

例如我们在 Docsify/zh-cn目录下创建一个 _sidebar.md，配置如下：

测试我们首先进入3000端口的首页

然后点击 zh-cn 后，可以看到该目录下的侧边栏，也就是上述配置的 Docsify/zh-cn/_sidebar.md

注意：_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取，我们也可以在 index.html 中如下配置表示默认都走根路径下的 _sidebar.md 文件

:page_facing_up: 开启侧边栏目录

自定义侧边栏后默认不会再生成目录，我们可以通过设置生成目录的最大层级开启这个功能：

当设置了 subMaxLevel 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 。

要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 。

在使用时， 和 都不会在页面上呈现。

添加导航栏有两种方式，一是直接到 index.html 中添加，二是和侧边栏类似，通过 md 文件的形式来添加：

:one: html中添加nav标签

:two: 通过md文件来添加

首先在 index.html 中配置 loadNavbar，默认加载的文件为 _navbar.md

然后在 Docsify 目录下创建 _navbar.md，这样设置与上述通过html的效果一致

此外，如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式：

注意：_navbar.md 加载逻辑和 sidebar 文件一致，从每层目录下获取。例如当前路由为 /zh-cn 那么是从 /zh-cn/_navbar.md 获取导航栏。

:page_facing_up: 整合自定义导航栏与 emoji 插件

如果你使用 emoji 插件:

例如，你可以在自定义导航栏 Markdown 文件中使用旗帜表情：

同侧边栏和导航栏一样，我们手下在 index.html 中设置 coverpage 参数开启封面功能

然后在文档根目录创建 _coverpage.md 文件，用于配置封面内容

:page_facing_up: 自定义背景

目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。


:page_facing_up: 多封面

如果你的文档网站是多语言的，或许你需要设置多个封面，例如你的文档目录结构如下

那么可以这样配置

目前支持的主题如下所示，我们只需要在 index.html 中引入想要的主题即可

以上就是 docsify 的一个基本的配置，更多的配置可以查看docsify官方文档根据自己的情况作出定制化修改，接下来我们将这个网站部署上线使得所有人都可以进行访问，以下分别介绍了部署到 Gitee Page 和部署到云服务两种方式。

我们在gitee上新建一个仓库Docsify

然后 git clone 到本地，然后在其中创建一个docs目录，然后把本地的 Docsify 目录拷贝到该目录中

然后我们重新将本地变更推送到 gitee 远程仓库中

然后我们填写要部署的目录

最后就生成了一个网站地址，我们点击直接可以访问了


这里我们采用 Nginx 反向代理服务器来部署，首先在云服务器上安装好 Nginx：Nginx最新版安装教程（Windows+Linux）

Nginx 安装完成后，我们访问服务器的公网ip即可进入nginx页面

接下来我们在 Nginx 安装目录也就是 /usr/local/nginx 下新建一个文件夹专门用来存放 Docsify 的文件

接下来我们将本地存放docsify文件的 Docsify 文件夹上传到服务器的 Docsify 文件夹即可

此时 docsify 相关文件已经上传到 nginx 的 Docsify 目录中，接下来我们将该路径配置到 nginx 配置文件中即可

将 location/root 地址更改为存放 docsify 文件的 Docsify 目录的地址即可，更改完保存退出

然后我们重启 nginx 服务器

完成后我们再次访问服务器的公网ip即可看到 docsify 的网站