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

背景

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

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

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

入門基礎

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

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

一些注意點

預覽

安裝文檔裏推薦安裝的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,所以整個網站的內容都會隨着文件的修改而實時更新,說實話還挺好用的。java

封面

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

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

代碼高亮

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

定製功能

由於整個項目自己就是以源碼的形式發佈的,因此給了用戶較大的定製空間,特別是對於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語言的支持堪稱完美。
如圖:dot.JPG

支持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>'
    );
}

就行。

試了一下,效果還能夠。
如圖:latex.JPG

總結

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

相關文章
相關標籤/搜索