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

上一篇文章選出了 docsify 作爲我的 Wiki 系統，這篇就來說下 docsify 的部署和配置。

官方推薦部署

docsify 快速開始文檔：https://docsify.js.org/#/quickstart

快速開始

安裝 docsify-cli 工具：

npm i docsify-cli -g

初始化項目：

docsify init ./docs

預覽網站：

docsify serve docs

部署到服務器

docsify 部署文檔：https://docsify.js.org/#/deploy

可以選擇部署到以下服務：

•GitHub Pages^[1]•GitLab Pages^[2]•Firebase Hosting^[3]•VPS^[4]•Netlify^[5]•ZEIT Now^[6]•AWS Amplify^[7]

我自己的部署

初始化項目

我在本地使用官方的構建工具進行初始化項目：

docsify init wiki

初始化之後其實有三個文件，index.html、README.md、.nojekyll。

•index.html：入口文件，docsify 的各項配置都在此頁面設置。•README.md：默認展示的首頁就是 README.md 裏的內容。•.nojekyll：用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件。

在本地編輯好文檔，通過下面命令即可本地預覽：

docsify serve wiki

上傳到Git

添加了文檔之後，我將整個 wiki 文件夾上到了「 Gitee^[8]」，爲什麼選 Gitee 呢，當然是國內訪問快而且免費了。

部署到Nginx

登陸我的服務器，生成 SSH 公鑰，生成方式可以參考「生成/添加SSH公鑰^[9]」，然後添加到 Gitee 的 「SSH 公鑰^[10]」。

然後在服務器使用 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 自定義配置文檔：https://docsify.js.org/#/configuration

各項配置都在 window.$docsify 裏。

我添加了如下配置，更多配置請參考上方文檔鏈接。

loadSidebar

加載自定義側邊欄，具體可以參考 https://docsify.js.org/#/more-pages。

loadSidebar: true,

增加 _sidebar.md 文件，編寫文件格式如下：

- [CentOS](centos.md)
- [Docker](docker.md)
- [Mac](mac.md)
- [NPM](npm.md)
- [推薦](recommend.md)

subMaxLevel

自定義側邊欄後默認不會再生成目錄，需要通過設置生成目錄的最大層級開啓這個功能。

subMaxLevel: 2,

配合 loadSidebar，效果如下：

subMaxLevel

auto2top

切換頁面後是否自動跳轉到頁面頂部。

auto2top: true,

name

文檔標題，顯示在側欄頂部。

name: '掘墓人的 Wiki',

nameLink

點擊文檔標題後跳轉的鏈接地址。

nameLink: '/',

點擊後跳轉到 Wiki 首頁。

routerMode

設置路由模式。

routerMode: 'history',

設置爲 history 之後，瀏覽器鏈接裏不會出現 #，個人習慣。

注意，設置爲 history，如果使用的是 Nginx 部署的項目，一定要加上下面的配置，否則在非首頁刷新會找不到頁面。

try_files $uri $uri/ /index.html;

coverpage

設置是否啓用封面頁，默認不啓用。

我沒有啓用封面，因爲我的 Wiki 不涉及到宣傳，就是自己查閱，所以應該打開就可以看到內容。

不過 docsify 的封面還是很好看的。

docsify

topMargin

讓你的內容頁在滾動到指定的錨點時，距離頁面頂部有一定空間。

topMargin: 40,

設置之後，點擊側欄的二級標題之後，頁面的標題不會距離頂部太近。

插件

docsify 插件文檔：https://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>

效果如下：

Full text search

Copy to Clipboard

複製到剪貼板，在所有的代碼塊上添加一個簡單的 Copy to Clipboard 按鈕來允許用戶從你的文檔中複製代碼。

需要引入 js 文件：

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

效果如下：

Copy to Clipboard

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>

效果如下：

Pagination

關於js文件

插件需要引入 js 文件，爲了訪問更穩定，我把所有的 js 文件都上傳到了又拍雲。

截止到發文，docsify 的最新版本是 4.11.3，查詢更多版本請查看「docsify releases^[11]」。

---

以上就是 docsify 部署及配置的全部內容了，更多詳細說明，可以查看「docsify 文檔^[12]」。

最後附上我的 Wiki 地址：掘墓人的 Wiki^[13]，歡迎查閱。

掘墓人的Wiki

相關閱讀：

Wiki系列（一）：Wiki系統選擇

引用鏈接

[1] GitHub Pages: https://docsify.js.org/#/deploy?id=github-pages
[2] GitLab Pages: https://docsify.js.org/#/deploy?id=gitlab-pages
[3] Firebase Hosting: https://docsify.js.org/#/deploy?id=firebase-hosting
[4] VPS: https://docsify.js.org/#/deploy?id=vps
[5] Netlify: https://docsify.js.org/#/deploy?id=netlify
[6] ZEIT Now: https://docsify.js.org/#/deploy?id=zeit-now
[7] AWS Amplify: https://docsify.js.org/#/deploy?id=aws-amplify
[8] Gitee: https://gitee.com/
[9] 生成/添加SSH公鑰: https://gitee.com/help/articles/4181
[10] SSH 公鑰: https://gitee.com/profile/sshkeys
[11] docsify releases: https://github.com/docsifyjs/docsify/releases
[12] docsify 文檔: https://docsify.js.org/
[13] 掘墓人的 Wiki: https://wiki.juemuren4449.com/