Wiki系列（二）：docsify部署及配置

上一篇文章选出了 docsify 做为个人 Wiki 系统，这篇就来讲下 docsify 的部署和配置。

官方推荐部署

docsify 快速开始文档：docsify.js.org/#/quickstar…

快速开始

安装 docsify-cli 工具：

npm i docsify-cli -g
复制代码

初始化项目：

docsify init ./docs
复制代码

预览网站：

docsify serve docs
复制代码

部署到服务器

docsify 部署文档：docsify.js.org/#/deploy

能够选择部署到如下服务：

• GitHub Pages
• GitLab Pages
• Firebase Hosting
• VPS
• Netlify
• ZEIT Now
• AWS Amplify

我本身的部署

初始化项目

我在本地使用官方的构建工具进行初始化项目：

docsify init wiki
复制代码

初始化以后其实有三个文件，index.html、README.md、.nojekyll。

• index.html：入口文件，docsify 的各项配置都在此页面设置。
• README.md：默认展现的首页就是 README.md 里的内容。
• .nojekyll：用于阻止 GitHub Pages 会忽略掉下划线开头的文件。

在本地编辑好文档，经过下面命令便可本地预览：

docsify serve wiki
复制代码

上传到Git

添加了文档以后，我将整个 wiki 文件夹上到了「 Gitee」，为何选 Gitee 呢，固然是国内访问快并且免费了。

部署到Nginx

登录个人服务器，生成 SSH 公钥，生成方式能够参考「生成/添加SSH公钥」，而后添加到 Gitee 的 「SSH 公钥」。

而后在服务器使用 git 拉取 Wiki 项目，固然要使用 SSH 地址，之后本地文档更新推送到 Gitee 以后，只要在服务器上拉取更新就能够了。

拉取以后，配置 Nginx 以下，便可经过域名访问：

• 设置 root 目录为 wiki 文件夹。
• 设置 index 为 index.html。
• 设置不缓存。

server {
  listen 80;
  server_name  wiki.juemuren4449.com;
    location / {
      try_files $uri $uri/ /index.html;
      root /usr/local/wiki;
      index  index.html index.htm;
      add_header Cache-Control "no-cache, no-store";
  }
}
复制代码

设置不缓存这个因人而异，我我的的 Wiki 刚开始积累，还在不断的完善，若是容许缓存，可能致使最新更新的内容不显示，等之后趋于完善，应该会设置容许缓存，或者直接放到 CDN 上。

为何没用CDN

因为 docsify 搭建的 Wiki 都是源文件，不须要本身编译，因此彻底能够把整个文档放到又拍云或者七牛云等 CDN 上，访问速度会更快。

但目前我仍是把 Wiki 部署到了个人服务器上，为何不直接放到 CDN 上呢，有如下几个缘由：

• CDN 默认是有缓存的，若是文件更新，访问的可能不是最新的文件。
• 我设置了 routerMode 为 history，使用 CDN 访问非首页，再次刷新会找不到文件。
• 若是开启了 relativePath: true，文件能够找到，可是侧栏上边的标题点击又有点问题。

若是使用默认的 routerMode，放在 CDN 上彻底可行。

自定义配置

docsify 自定义配置文档：docsify.js.org/#/configura…

各项配置都在 window.$docsify 里。

我添加了以下配置，更多配置请参考上方文档连接。

loadSidebar

加载自定义侧边栏，具体能够参考 docsify.js.org/#/more-page…。

loadSidebar: true,
复制代码

增长 _sidebar.md 文件，编写文件格式以下：

- [CentOS](centos.md)
- [Docker](docker.md)
- [Mac](mac.md)
- [NPM](npm.md)
- [推荐](recommend.md)
复制代码

subMaxLevel

自定义侧边栏后默认不会再生成目录，须要经过设置生成目录的最大层级开启这个功能。

subMaxLevel: 2,
复制代码

配合 loadSidebar，效果以下：

auto2top

切换页面后是否自动跳转到页面顶部。

auto2top: true,
复制代码

name

文档标题，显示在侧栏顶部。

name: '掘墓人的 Wiki',
复制代码

nameLink

点击文档标题后跳转的连接地址。

nameLink: '/',
复制代码

点击后跳转到 Wiki 首页。

routerMode

设置路由模式。

routerMode: 'history',
复制代码

设置为 history 以后，浏览器连接里不会出现 #，我的习惯。

注意，设置为 history，若是使用的是 Nginx 部署的项目，必定要加上下面的配置，不然在非首页刷新会找不到页面。

try_files $uri $uri/ /index.html;
复制代码

coverpage

设置是否启用封面页，默认不启用。

我没有启用封面，由于个人 Wiki 不涉及到宣传，就是本身查阅，因此应该打开就能够看到内容。

不过 docsify 的封面仍是很好看的。

topMargin

让你的内容页在滚动到指定的锚点时，距离页面顶部有必定空间。

topMargin: 40,
复制代码

设置以后，点击侧栏的二级标题以后，页面的标题不会距离顶部太近。

插件

docsify 插件文档：docsify.js.org/#/plugins

docsify 有丰富的插件，能够按需添加。

Full text search

全局搜索

search: {
  paths: 'auto',
  placeholder: '请输入要搜索的关键字',
  noData: '没有结果',
  depth: 6,
},
复制代码

开启全局搜索须要引入两个 js 文件：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
复制代码

效果以下：

Copy to Clipboard

复制到剪贴板，在全部的代码块上添加一个简单的 Copy to Clipboard 按钮来容许用户从你的文档中复制代码。

须要引入 js 文件：

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
复制代码

效果以下：

Pagination

分页导航，在文档的最下方会展现上一个文档和下一个文档。

pagination: {
  previousText: '上一章节',
  nextText: '下一章节',
}
复制代码

须要引入两个 js 文件：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
复制代码

效果以下：

关于js文件

插件须要引入 js 文件，为了访问更稳定，我把全部的 js 文件都上传到了又拍云。

截止到发文，docsify 的最新版本是 4.11.3，查询更多版本请查看「docsify releases」。

---

以上就是 docsify 部署及配置的所有内容了，更多详细说明，能够查看「docsify 文档」。

最后附上个人 Wiki 地址：掘墓人的 Wiki，欢迎查阅。

相关阅读：

Wiki系列（一）：Wiki系统选择

欢迎访问的我的博客：掘墓人的小铲子