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系統選擇

歡迎訪問的我的博客：掘墓人的小鏟子