使用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
.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渲染器是我第一次在源碼級別定制軟件，之前覺得這對我來說簡直是不可能的事，真實嘗試之後發現其實自己已經有這個能力了。當然自己離一些大牛還差得很遠，特別是數學、數據結構和算法方面，自己需要彌補的東西還有很多。不要驕傲自大，也不要妄自菲薄，清楚認識自己的實力並不斷增強，此乃王道也。
使用docsify並定制以使它更強大