使用docsify並定製以使它更強大

背景

常常在網上看到一些排版很是漂亮的技術手冊，左邊有目錄欄，右邊是Markdown格式的文檔，整個配色都十分舒服，就像一本書同樣，一看就很讓人喜歡。就好比Markdown Preview Enhanced的文檔.目前網上我瞭解的有兩種工具能夠實現這樣的效果，一種叫作docsify，另外一種叫作Gitbook。由於MPE文檔用的是docsify，並且據docsify本身的宣傳，說是

不一樣於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，全部轉換工做都是在運行時進行。
這將很是實用，若是隻是須要快速的搭建一個小型的文檔網站，或者不想由於生成的一堆 .html 文件「污染」 commit 記錄，只須要建立一個 index.html 就能夠開始寫文檔並且直接部署在 GitHub Pages。

因此我也就用它來作吧。這裏先放上個人成品：https://aopstudio.github.io/docs

入門基礎

具體的一些基本操做它的官方文檔上面都已經寫得很明白了，我就再也不贅述了，官方文檔地址：https://docsify.js.org/#/zh-cn/ 。它的官方文檔自己就是用docsify寫的，讓使用者第一眼就能感覺到docsify生成文檔的效果。

其實我每篇博客都不會去贅述官方文檔裏面已經有的內容，儘管這樣能夠湊字數，可是沒什麼意義。

一些注意點

預覽

安裝文檔裏推薦安裝的docisfy-cli工具，能夠方便地預覽文檔網站。用docsify serve docs命令就能夠用瀏覽器訪問localhost:3000預覽。須要注意的是serve後面的不是當前所在文件夾，而是當前目錄的子文件夾，也就是說若是你在D:\\docs建立了你的項目，你就應該在D:\\執行這條命令才能成功，而不是進到D:\\docs執行。若是進入到了D:\\docs，就應當寫docsify serve，這樣的話預覽的就是當前文件夾的內容。有意思的是，若是我把docsify的文件夾做爲一個子文件夾放在個人整個網站目錄中時，好比個人網站根目錄是/www，docsify項目在/www/docs，若是在網站根目錄執行docsify serve，預覽出來的就是整個網站，並且由於docsify採用了vue.js，所以整個網站的內容都會隨着文件的修改而實時更新，說實話還挺好用的。

封面

官方文檔中說要給開啓渲染封面功能後在文檔根目錄建立_coverpage.md文件，以後就能在預覽頁面看到封面。可是根據我本身的嘗試這樣實際上是有問題的，在本地預覽時的確能夠看到封面，但一放到Github Pages裏面封面就沒了。我我的認爲是Github Pages默認使用的Jekyll會把如下劃線開頭的文件忽略掉。而做者應該也想到了這個問題，因此在文檔的文件夾裏面放了一個文件名爲.nojekyll用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件，但不知怎麼的，反正是沒起到什麼做用，它照樣忽略了。

不過封面沒法顯示的問題很好解決，建立一個不如下劃線開頭的封面文件自定義封面路徑就行。也就是把配置項中的coverpage: true改成coverpage: 自定義的封面文件路徑就行。

代碼高亮

默認代碼高亮是隻支持CSS、JavaScript 和 HTML語言的。照官方文檔裏的說法想要支持其餘語言須要手動引入高亮插件。不過我試了試照文檔裏的說法手動引入高亮插件，並無什麼用。我想盡各類辦法，甚至都開始對在源碼級別動刀子了，仍是沒有用（後文會提到兩個在源碼級別動刀子成功的案例，但惟獨這個是失敗的）。吐槽一下吧，一看做者就是一個前端程序員，要是是後端程序員寫的話，不可能只支持這三門語言的。

定製功能

由於整個項目自己就是以源碼的形式發佈的，因此給了用戶較大的定製空間，特別是對於Markdown渲染器。項目自帶的默認Markdown渲染器只支持基本的語法，沒有目前大部分Markdown寫做工具都支持的一些擴展語法，好比LaTex數學公式、流程圖等等。個人筆記中對於數學公式和圖用到的仍是很是多的，所以我就想改進一下它的渲染器，讓它能支持這兩個功能。

首先感謝JavaScript這門語言，正是這門語言讓我在理論上能實現此次改進。其次感謝一下BootCDN，大家提供的CDN服務使依賴文件的處理如此方便。

支持DOT語言做圖

DOT語言是貝爾實驗室開發的用於做圖的腳本語言，最初在桌面端程序Graphviz中支持。後來有人開發了Viz.js使得瀏覽器端也能支持DOT語言做圖的渲染。

咱們的目的以下：當Markdown渲染器識別到一處語言名爲dot的代碼塊時，就調用Viz.js渲染代碼塊中的語句，使它們成爲DOT語言定義的矢量圖。

具體操做以下：（如下全部操做都在docsify項目的index.html文件中進行）

首先，引入Viz.js文件，推薦使用BootCDN的服務，只要在head中添加一條語句就行：<script src="https://cdn.bootcss.com/viz.js/1.8.0/viz.js"></script>。這裏須要提醒一句，引入的viz.js文件必須是2.0版本如下的，千萬不要爲圖新版本而引入2.0版本以後的，2.0版本以後的支持方式發生了改變，網上相關的資料極少，我本人是沒有研究出來。引入1.8.0版本是很是穩妥的。

以後的操做能夠參考文檔裏的這部份內容：https://docsify.js.org/#/zh-cn/markdown?id=%E6%94%AF%E6%8C%81-mermaid .我本人就是參考這部份內容才實現的。不一樣的是，須要把

if (lang === "mermaid") {
    return (
    '<div class="mermaid">' + mermaid.render(lang, code) + "</div>"
    );
}

改爲

if (lang === "dot") {
    return (
    '<div class="viz">'+ Viz(code, "SVG")+'</div>'
    );
}

這樣定製以後，文檔對於DOT語言的支持堪稱完美。
如圖：

支持LaTex數學公式

LaTeX是大門鼎鼎的文檔排版軟件，它對於數學公式的支持很是好。和DOT語言相似，一開始也是隻有桌面端程序支持，可是後來一樣有人開發了各類各樣的.js來在瀏覽器端進行支持，咱們這裏使用的是katex.js。

首先引入katex.js，在head中添加

<link href="https://cdn.bootcss.com/KaTeX/0.10.0/katex.min.css" rel="stylesheet">
<script src="https://cdn.bootcss.com/KaTeX/0.10.0/katex.min.js"></script>

通常來講Markdown文檔中數學公式會用$包圍表示，可是我作不到這麼細的地步，仍是隻能讓Markdown渲染器和支持DOT語言同樣，把數學公式看成一門編程語言來渲染。所以須要將公式用```tex ```進行包圍，以質能轉換公式爲例，應當這樣寫：

```tex
        E=mc^2
    ```

這樣比用$包圍麻煩，但好歹能用。

一樣參照上面的作法，須要把

if (lang === "mermaid") {
    return (
    '<div class="mermaid">' + mermaid.render(lang, code) + "</div>"
    );
}

改爲

if (lang === "tex") {
    return (
    '<span class="tex">'+ katex.renderToString(code, {
        throwOnError: false
    })+'</span>'
    );
}

就行。

試了一下，效果還能夠。
如圖：

總結

定製docsify的Markdown渲染器是我第一次在源碼級別定製軟件，以前以爲這對我來講簡直是不可能的事，真實嘗試以後發現其實本身已經有這個能力了。固然本身離一些大牛還差得很遠，特別是數學、數據結構和算法方面，本身須要彌補的東西還有不少。不要驕傲自大，也不要妄自菲薄，清楚認識本身的實力並不斷加強，此乃王道也。