幾分鐘上線一個項目文檔網站，這款開源神器實在太香了

之前在搭建mall項目的文檔網站時，使用過不少工具，比如說Docsify、VuePress、Hexo、語雀等。對比了一下，要論使用簡單、上線快捷還是Docsify，幾分鐘上線一個網站也不是問題，今天我們就來聊聊Docsify的使用！

SpringBoot實戰電商項目mall（50k+star）位址：github.com/macrozheng/…

簡介

Docsify是一款開源的文檔生成工具，目前在Github上已有21K+Star。Docsify可以快速幫你生成文檔網站，不同于VuePrese和Hexo的地方是它不會生成靜态的.html檔案，所有轉換工作都是在運作時。

安裝

使用Docsify僅需安裝NodeJs和Docsify的CLI工具即可，非常簡單。

安裝NodeJs

• 首先下載下傳NodeJs的安裝包，下載下傳位址：nodejs.org/dist/v12.14…
• 下載下傳完成後一路點選下一步安裝即可，如果你想修改npm的子產品安裝路徑和緩存路徑的話，可以使用如下指令；

# 修改npm的全局安裝子產品路徑
npm config set prefix "D:\developer\env\node-v12.14.0\node_global"
# 修改npm的緩存路徑
npm config set cache "D:\developer\env\node-v12.14.0\node_cache"
複制代碼           

• 然後添加系統環境變量NODE_PATH；

NODE_PATH = D:\developer\env\node-v12.14.0
複制代碼           

• 再在系統環境變量的Path中添加如下路徑即可。

%NODE_PATH%\
%NODE_PATH%\node_global\
複制代碼           

安裝docsify-cli工具

• 安裝完NodeJs後，可使用如下指令安裝Docsify的CLI工具。

npm i docsify-cli -g
複制代碼           

使用

環境安裝完成後，下面我們來聊聊Docsify的使用。

初始化項目

• 首先我們需要使用如下指令初始化一個項目，注意提示找不到docsify指令的話，多半是NodeJs的環境變量配置有問題。

docsify init ./docs
複制代碼           

• 項目初始化完成後基本結構如下

-| docs/
  -| .nojekyll
  -| index.html
  -| README.md
複制代碼           

實時預覽

• 如果你想實時預覽項目的話，可以使用如下指令；

docsify serve docs
複制代碼           

• 啟動還是非常快速的，下面是我改造完成的文檔網站最終效果圖，還是不錯的，通路位址：http://localhost:3000

定制側邊欄

• 從上面的效果圖大家可以看到，左側有個側邊欄用于顯示文檔目錄和大綱，側邊欄可以在index.html檔案中進行配置；

<script>
  window.$docsify = {
    loadSidebar: true,
    maxLevel: 2,
    subMaxLevel: 4,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'//防止意外回退
    }
  }
</script>

<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
複制代碼           

• 然後在docs目錄下添加側邊欄的配置檔案_sidebar.md，添加如下配置即可；

* 序章
    * [mall架構及功能概覽](foreword/mall_foreword_01.md)
    * [mall學習所需知識點](foreword/mall_foreword_02.md)
* 架構篇
    * [mall整合SpringBoot+MyBatis搭建基本骨架](architect/mall_arch_01.md)
    * [mall整合Swagger-UI實作線上API文檔](architect/mall_arch_02.md)
複制代碼           

• 此時我們就可以看到網站左側出現側邊欄了，大家可以發現Docsify不同于VuePress，可以直接使用Markdown進行側邊欄配置。

定制導航欄

• Docsify還支援頂部導航欄的配置，直接修改index.html檔案，添加如下配置；

<script>
  window.$docsify = {
    loadNavbar: true,
    alias: {
      '/.*/_navbar.md': '/_navbar.md'//防止意外回退
    }
  }
</script>
複制代碼           

• 然後建立_navbar.md檔案，添加如下配置即可；

* 示範
  * [背景管理](http://www.macrozheng.com/admin/index.html)
  * [移動端](http://www.macrozheng.com/app/mainpage.html)

* 項目位址
  * [背景項目](https://github.com/macrozheng/mall)
  * [前端項目](https://github.com/macrozheng/mall-admin-web)
  * [學習教程](https://github.com/macrozheng/mall-learning)
  * [項目骨架](https://github.com/macrozheng/mall-tiny)

* SpringCloud
  * [SpringCloud版本](https://github.com/macrozheng/mall-swarm)
  * [SpringCloud教程](https://github.com/macrozheng/springcloud-learning)
複制代碼           

• 此時我們的文檔網站頂部就可以顯示導航欄了。

定制封面頁

• Docsify還支援封面頁的配置，直接修改index.html檔案，添加如下配置；

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
複制代碼           

• 然後建立_coverpage.md檔案，添加如下配置即可；

![logo](images/mall.svg)
# mall-learning
> mall學習教程，架構、業務、技術要點全方位解析。

mall項目（50k+star）是一套電商系統，使用現階段主流技術實作。  
涵蓋了SpringBoot、MyBatis、Elasticsearch、RabbitMQ、
Redis、MongoDB、Mysql等技術，采用Docker容器化部署。

[GitHub](https://github.com/macrozheng/mall-learning)
[Get Started](README.md)
複制代碼           

• 此時封面頁将展示如下效果，你在修改配置的時候可以發現，Docsify修改配置和内容後可以立刻生效，非常快速，比起VuePress的編譯快多了。

插件

Docsify還有豐富的插件支援，這裡我們我們聊聊一些常用的插件使用。

全文搜尋

• 如果你想實作全文搜尋功能的話，可以在index.html中添加搜尋插件配置；

<script>
  window.$docsify = {
    search: {
      placeholder: '搜尋',
      noData: '找不到結果!',
      depth: 3
    },
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
複制代碼           

• 添加成功後，文檔網站左上角即可開啟搜尋功能。

代碼高亮

• 如果你想實作代碼高亮顯示的話，可以在index.html中添加代碼高亮的插件；

<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-xml.min.js"></script>
複制代碼           

• 以上是幾種常見的代碼高亮顯示插件，添加完成後就可以實作代碼的高亮顯示的。

一鍵複制代碼

• 如果你想實作一鍵複制代碼，Docsify也是有插件可以支援的，直接在index.html中添加如下插件即可；

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>
複制代碼           

• 添加完成後，在我們代碼的右上角就會出現複制代碼按鈕了。

更換主題

• Docsify預設的主題雖然不錯，但有沒有其他主題可以更換呢，這裡推薦一款令人愉悅的主題docsify-themeable，這裡修改下index.htmlhead中導入的css代碼即可；

<head>
<!--  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">-->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
</head>
複制代碼           

• 本文使用的就是這種主題，此主題擁有側邊欄折疊和隐藏功能，用起來還是挺不錯的。

更多插件

Docsify的擴充插件還是挺多的，如果你想尋找更多插件的話，不妨參考下這個開源項目。

github.com/docsifyjs/a…

部署

• 使用Nginx來部署Docsify也是非常簡單的，我們先來回顧下之前的項目目錄；

• 在使用VuePress時，我們需要把Markdown檔案編譯成html才能部署，使用Docsify我們無需編譯，隻需把docs中的文檔都拷貝到Nginx的html目錄中即可；

• 此時我們啟動Nginx，通路下Nginx服務路徑即可檢視文檔。

總結

今天帶大家體驗了一把Docsify，使用Docsify來搭建文檔網站确實簡單、快捷。對比使用VuePress和Hexo來搭建文檔，雖然功能沒有那麼強大，但是Docsify無需編譯、無需打包部署、修改響應迅速、對Markdown文檔無污染這些優點還是值得肯定的。另外Docsify除了一些插件配置，其他配置基本可以使用Markdown來完成，感興趣的小夥伴不妨嘗試下它！

參考資料

官方文檔：docsify.js.org/#/zh-cn/

來源：https://juejin.cn/post/7163451101549690893