入坑 docsify，一款神奇的文檔生成利器！

Guide 哥是我認識的一個非常優(yōu)秀的年輕人，胖嘟嘟的身軀里充斥著無窮無盡的才華，他的 JavaGuide 在 GitHub 上已經(jīng)標星 91K+ 了，空閑的時候我都會上去瞅兩眼，畢竟學習使我快樂，嘿嘿。

有一天，我發(fā)現(xiàn)，他整的那個在線版看起來非常漂亮，我就問他用什么做的，他就會回我說，“docsify，很方便。”剛好我最近在更新《教妹學 Java》專欄，就也想整個在線版的，方便讀者閱讀。

01、docsify 是什么

一款神奇的文檔生成利器

自從有了 Markdown， 我就再沒用過富文本編輯器，因為 Markdown 的書寫有一種心流的感覺。很多博客平臺都支持 Markdown 了，即便是不支持，也沒關(guān)系，可以通過 mdnice 或者 Md2All 轉(zhuǎn)成富文本的格式。

docsify 可以自動地將 Markdown 中的標題生成目錄，并且可以配合碼云（國內(nèi)的訪問速度比 GitHub Pages 更快）快速搭建一個小型的文檔網(wǎng)站，整個頁面的配色和布局也十分舒適，讓閱讀體驗在不知不覺中提升了好幾個檔次。

和 Gitbook 不同，docsify 不會生成靜態(tài)的 HTML 文件，它會智能地加載和解析 Markdown 文件，這就避免了 HTML 文件對整個文檔庫的“污染”。

貼一下 docsify 的官網(wǎng)：

https://docsify.js.org/

點進去后你會感覺非常的賞心悅目，滿滿的小清新。不得不承認，我的眼睛被它深深地吸引了。

02、入坑 docsify

第一步，打開命令行，執(zhí)行以下命令安裝 docsify-cli，方便本地初始化和實時預覽。

npm?i?docsify-cli?-g

如果這一步非常非常慢的話，可以強制退出，因為 npm 是從國外服務器下載的，受網(wǎng)絡(luò)影響較大。

淘寶團隊幫我們解決了這個煩惱，搞了一個 npm 的國內(nèi)鏡像。可以通過執(zhí)行下面的命令把 npm 替換成 cnpm。

npm?install?-g?cnpm?--registry=https://registry.npm.taobao.org

如果出現(xiàn) Error: EACCES: permission denied, access '/usr/local/lib/node_modules' 錯誤的話，是因為執(zhí)行命令時沒有獲得管理員權(quán)限，解決方案就在 npm 前面加上 sudo：

sudo?npm?install?-g?cnpm?--registry=https://registry.npm.taobao.org

輸入密碼后就可以執(zhí)行成功了。然后執(zhí)行 cnpm i docsify-cli -g 命令進行安裝。如果還提示權(quán)限錯誤（Error: EACCES: permission denied）的話，記得加上 sudo。

PS：sudo 是一個 linux 系統(tǒng)管理指令，允許系統(tǒng)管理員讓普通用戶執(zhí)行一些 root 級別的命令。

安裝成功后，會提示以下信息。

第二步，執(zhí)行以下命令創(chuàng)建文檔目錄并初始化。

docsify?init?./docs

進入 docs 目錄后，可以看到 README.md（做為主頁內(nèi)容渲染）和 index.html（入口文件）兩個文件。

第三步，回到 docs 的上級目錄，執(zhí)行以下命令啟動本地服務。

docsify?serve?docs

第四步，在瀏覽器地址欄輸入 http://localhost:3000 進行預覽。

03、自定義導航欄

打開 index.html 文件，在 body 標簽中添加 nav 標簽，如下所示：

??
??"app">

保存后，就可以在瀏覽器上查看到效果。

04、定制化配置項

打開 index.html 文件，在 script 標簽中對 window.$docsify 進行配置，如下所示：

window.$docsify?=?{
????????name:?'教妹學Java',
????????repo:?'https://github.com/itwanger/TechSisterLearnJava',
}

1）name：文檔標題，會顯示在側(cè)邊欄頂部。

2）repo：GitHub 上的倉庫地址，會在頁面右上角渲染一個 GitHub 角標。

保存后，就可以在瀏覽器上查看到效果。

05、安裝插件

1）全文搜索

全文搜索插件會根據(jù)當前頁面上的超鏈接獲取文檔內(nèi)容，在 localStorage 內(nèi)建立文檔索引。默認過期時間為一天，也可以指定需要緩存的文件列表或者過期時間。

打開 index.html 文件，添加全文搜索配置項，并引入 search.min.js，如下所示：

??
??

保存后，就可以在瀏覽器上查看到效果。

2）圖片縮放

在 index.html 文件中引入 zoom-image.min.js 即可，如下所示：

保存后，就可以在瀏覽器上查看到效果，鼠標放到一張圖片上時會出現(xiàn)縮小或者放大的圖標，點擊后就可以改變圖片的形態(tài)。

3）復制到剪貼板

在所有的代碼塊上添加一個簡單的 Click to copy 按鈕來允許用戶從你的文檔中輕易地復制代碼。在 index.html 文件中引入 docsify-copy-code 即可，如下所示：

保存后，就可以在瀏覽器上查看到效果。

4）字數(shù)統(tǒng)計

提供了統(tǒng)計中文漢字和英文單詞的功能，并且排除了一些 markdown 語法的特殊字符例如 *、- 等。

打開 index.html 文件，添加 count 配置項，并引入 countable.js，如下所示：

??

保存后，就可以在瀏覽器上查看到效果。

06、代碼高亮

docsify 內(nèi)置的代碼高亮工具是 Prism。Prism 默認支持的語言如下：

• Markup -?markup,?html,?xml,?svg,?mathml,?ssml,?atom,?rss
• CSS -?css
• C-like -?clike
• JavaScript -?javascript,?js

Java 需要在 index.html 文件中添加額外的語法文件，如下所示：

保存后，就可以在瀏覽器上查看到效果。

07、部署到碼云

我們可以把文檔網(wǎng)站部署到 GitHub Pages 上，但對于國內(nèi)用戶來說，碼云的訪問速度顯然會更快一些。

如果你是第一次使用 GitHub 的話，我這里已經(jīng)為你準備好了教程：

文科妹子都會用 GitHub，你這個工科生還等什么

在 GitHub 上新建一個倉庫，把你的文檔全部放到 docs 目錄下，我的已經(jīng)創(chuàng)建好了，就叫 TechSisterLearnJava。

接下來，登錄碼云，選擇從 GitHub 導入倉庫。

選擇對應倉庫后點擊導入。

導入成功后，點擊「查看倉庫」，就可以看到從 GitHub 導入到碼云的倉庫。點擊「服務」，選擇「Gitee Pages」。

勾選強制啟用 HTTPS，然后點擊「啟動」按鈕。不一會兒，碼云 Pages 服務就開啟了。

點擊網(wǎng)站地址：

https://itwanger.gitee.io/sister-learn-java

就可以看到 docsify 已經(jīng)成功部署到碼云上了。

08、最后

強烈推薦一下《教妹學 Java》專欄，目前已更新 15 節(jié)內(nèi)容（近 5 萬字），后面每周至少會更新 2 節(jié)，預計更新 130 節(jié)，從 Java 的基礎(chǔ)知識到對象和類，再到集合框架、網(wǎng)絡(luò)編程、并發(fā)編程和 Java 虛擬機，基本上全方位覆蓋。

專欄中涉及到的圖片都花了我很多精力和心思，力爭給你一種耳目一新的感覺，隨便截幾張圖給你看看。

這么好的專欄上哪去找呢？免費給你（反正我也不知道自己是怎么想的）！

GitHub 閱讀地址（star 它）：

https://github.com/itwanger/sister-learn-java

碼云閱讀地址（star 它）：

https://gitee.com/itwanger/sister-learn-java

docsify 在線閱讀地址：

https://itwanger.gitee.io/sister-learn-java

我知道，我知道，不用你開口，離線版的 PDF 我也準備好了，看這暗黑風格的 PDF，閱讀起來絕壁賞心悅目啊。

百度網(wǎng)盤下載地址：

https://pan.baidu.com/s/1T1gNwQB8nKsrIzHveJ9WKg ?提取碼:8tw7

PS：整完這個 docsify 后，我累壞了，一瞅時間，凌晨 1 點 32 分了，說實話，眼睛已經(jīng)迷離了。