docsify 構建文檔網站之定製功能（全網最全）

原創 吴跟强 2020-07-07 04:03

文檔後續更新地址：docsify 構建文檔網站

4 定製功能

文章目錄

4.1 支持 DOT 語言作圖

DOT 語言是貝爾實驗室開發的用於作圖的腳本語言，最初在桌面端程序 Graphviz 中支持。後來有人開發了 Viz.js 使得瀏覽器端也能支持 DOT 語言作圖的渲染。我們的目的如下：當 Markdown 渲染器識別到一處語言名爲 dot 代碼塊時，就調用 Viz.js 渲染代碼塊中的語句，使它們成爲 DOT 語言定義的矢量圖。

具體操作如下：（以下所有操作都在 docsify 項目的 index.html 文件中進行）

  • （1）首先，引入 Viz.js 文件，只要在 head 中添加一條語句就行：
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/viz.js"></script>
  • （2）添加如下部分：
<script>
    window.$docsify = {
      markdown: {
        renderer: {
          code: function(code, lang) {
            if (lang === "dot") {
              return (
                      '<div class="viz">'+ Viz(code, "SVG")+'</div>'
              );
            }
            return this.origin.code.apply(this, arguments);
          }
        }
      }
    }
  </script>

下面看看具體實現：

  • 操作：
​```dot
digraph demo{
    A->B[dir=both];
    B->C[dir=none];
    C->D[dir=back];
    D->A[dir=forward];
}
​```
  • 效果圖：
digraph demo{
    A->B[dir=both];
    B->C[dir=none];
    C->D[dir=back];
    D->A[dir=forward];
}

4.2 支持 LaTex 數學公式

LaTeX 是大門鼎鼎的文檔排版軟件，它對於數學公式的支持非常好。和 DOT 語言類似，一開始也是隻有桌面端程序支持，但是後來同樣有人開發了各種各樣的 .js 來在瀏覽器端進行支持。

具體操作如下：（以下所有操作都在 docsify 項目的 index.html 文件中進行）

  • （1）引入 docsify-katex.js，head 中添加：
<!-- CDN files for docsify-katex -->
<script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
<!-- or <script src="//cdn.jsdelivr.net/gh/upupming/docsify-katex@latest/dist/docsify-katex.js"></script> -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css"/>

下面看看具體實現：

  • 操作：
$$
\left[
\begin{matrix}
 1      & 2      & \cdots & 4      \\
 7      & 6      & \cdots & 5      \\
 \vdots & \vdots & \ddots & \vdots \\
 8      & 9      & \cdots & 0      \\
\end{matrix}
\right]
$$
  • 效果圖：

[12⋯476⋯5⋮⋮⋱⋮89⋯0] \left[ \begin{matrix} 1 & 2 & \cdots & 4 \\ 7 & 6 & \cdots & 5 \\ \vdots & \vdots & \ddots & \vdots \\ 8 & 9 & \cdots & 0 \\ \end{matrix} \right]

更多 Latex 矩陣樣式請參考 使用 Latex 寫矩陣

4.3 支持 PDF 頁面展示

  • （1）在 index.html 中添加插件：
<!-- PDFObject.js is a required dependency of this plugin -->
<script src="//cdnjs.cloudflare.com/ajax/libs/pdfobject/2.1.1/pdfobject.min.js"></script> 
<!-- docsify-pdf-embed.js  -->
<script src="//unpkg.com/docsify-pdf-embed-plugin/src/docsify-pdf-embed.js"></script>
  • （2）在 index.html 中添加代碼：
markdown: {
        renderer: {
          code: function(code, lang, base=null) {

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

            var pdf_renderer = function(code, lang, verify) {
              function unique_id_generator(){
                function rand_gen(){
                  return Math.floor((Math.random()+1) * 65536).toString(16).substring(1);
                }
                return rand_gen() + rand_gen() + '-' + rand_gen() + '-' + rand_gen() + '-' + rand_gen() + '-' + rand_gen() + rand_gen() + rand_gen();
              }
              if(lang && !lang.localeCompare('pdf', 'en', {sensitivity: 'base'})){
                if(verify){
                  return true;
                }else{
                  var divId = "markdown_code_pdf_container_" + unique_id_generator().toString();
                  var container_list = new Array();
                  if(localStorage.getItem('pdf_container_list')){
                    container_list = JSON.parse(localStorage.getItem('pdf_container_list'));
                  }
                  container_list.push({"pdf_location": code, "div_id": divId});
                  localStorage.setItem('pdf_container_list', JSON.stringify(container_list));
                  return (
                          '<div style="margin-top:'+ PDF_MARGIN_TOP +'; margin-bottom:'+ PDF_MARGIN_BOTTOM +';" id="'+ divId +'">'
                          + '<a href="'+ code + '"> Link </a> to ' + code +
                          '</div>'
                  );
                }
              }
              return false;
            }
            if(pdf_renderer(code, lang, true)){
              return pdf_renderer(code, lang, false);
            }
            //return this.origin.code.apply(this, arguments);
            return (base ? base : this.origin.code.apply(this, arguments));
          }
        }
      }
  • （3）使用命令：
​```pdf
path-to-the-pdf-file,,,example: https://wugenqiang.gitee.io/file-storage/pdf.js/web/viewer.html?file=../../%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0/%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E5%9F%BA%E7%A1%80%E6%95%99%E7%A8%8B.pdf
​```

結果展示：

https://wugenqiang.gitee.io/file-storage/pdf.js/web/viewer.html?file=../../%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0/%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E5%9F%BA%E7%A1%80%E6%95%99%E7%A8%8B.pdf

4.4 支持回到頂部

方法：通過 jQuery 定義插件 jQuery GoUp 實現點擊回到頂部功能。

  • 效果圖如下：

操作如下：

  • （1）引用 jquery 庫和 jquery.goup.js 到 index.html
  <script src="https://wugenqiang.github.io/CS-Notes/plugin/jquery.js"></script>
  <script src="https://wugenqiang.github.io/CS-Notes/plugin/jquery.goup.js"></script>
  • 在調用下插件：
<script type="text/javascript">
    $(document).ready(function () {
      $.goup({
        trigger: 100,
        bottomOffset: 32,
        locationOffset: 32,
        title: 'TOP',
        titleAsText: true
      });
    });
  </script>

4.5 點擊頁面出現愛心

在 index.html 中複製下面代碼：

<!-- mouse click -->
<script src="//cdn.jsdelivr.net/gh/jerryc127/[email protected]/js/click_heart.js"></script>

4.6 定製評論功能

4.6.1 來必力評論

在 index.html 中 window.$docsify中添加代碼：

plugins: [
        /*來必力評論*/
        function (hook, vm) {
          // load livere
          hook.beforeEach(function(content) {
            var comment = "<div id='lv-container' data-id='city' data-uid='MTAyMC80MzA4MC8xOTYyNg=='></div>\n\n----\n"
            return content + comment;
          });

          hook.doneEach(function() {
            (function(d, s) {
              var j, e = d.getElementsByTagName(s)[0];
              if (typeof LivereTower === 'function') { return; }
              j = d.createElement(s);
              j.src = 'https://cdn-city.livere.com/js/embed.dist.js';
              j.async = true;
              e.parentNode.insertBefore(j, e);
            })(document, 'script');
          });
        },
      ]

效果圖：

image-20200506204834171

4.6.2 Gitalk 評論

  • （1）申請 Gitalk

申請網址：https://github.com/settings/applications/new

要是覺得自己填的不好或者填錯了，沒關係，這個後面是可以改的

註冊完畢之後，會進入這個界面：

image-20200519110724130

在這裏，你就能看到 clientID 和 clientSecret 啦，頁面不要關閉，先記錄一下這兩個值，下面有用。

  • （2）修改 index.html

添加下面代碼：(以我的舉例，適當修改)

<!-- Gitalk 評論系統 -->
<link rel="stylesheet" href="https://wugenqiang.gitee.io/notebook/plugin/gitalk.css">
<!-- Gitalk 評論系統 -->
<script src="https://wugenqiang.gitee.io/notebook/plugin/gitalk.js"></script>
<script src="https://wugenqiang.gitee.io/notebook/plugin/gitalk.min.js"></script>
<script src="https://wugenqiang.gitee.io/notebook/plugin/md5.min.js"></script>
<script>
  // title_id需要初始化
  window.title_id = window.location.hash.match(/#(.*?)([?]|$)/) ? window.location.hash.match(/#(.*?)([?]|$)/)[1] : '/';
  const gitalk = new Gitalk({
    clientID: 'b631e65d2e0ceb90837c',
    clientSecret: 'ff821461c12519b13271850829c32e5842cf9619',
    repo: 'NoteBook',
    owner: 'wugenqiang',
    admin: ['wugenqiang'],
    title: decodeURI(window.title_id),
    distractionFreeMode: false,	// 是否添加全屏遮罩
    id: md5(window.location.hash),	// 頁面的唯一標識，gitalk 會根據這個標識自動創建的issue的標籤,我們使用頁面的相對路徑作爲標識
    enableHotKey: true,	// 提交評論快捷鍵(cmd/ctrl + enter)
  })
  // 監聽URL中hash的變化，如果發現換了一個MD文件，那麼刷新頁面，解決整個網站使用一個gitalk評論issues的問題。
  window.onhashchange = function (event) {
    if (event.newURL.split('?')[0] !== event.oldURL.split('?')[0]) {
      location.reload()
    }
  }
</script>
  • （3）效果圖：

image-20200519114849679

4.6.3 Disqus 評論

在 index.html 中添加：

<script>
  window.$docsify = {
    disqus: 'shortname'
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/disqus.min.js"></script>

效果圖：

image-20200519143705984

4.7 複製文章彈窗提示

在 index.html 中寫入：

<!-- alert 樣式 -->
<link rel="stylesheet" href="https://cdn.bootcss.com/sweetalert/1.1.3/sweetalert.min.css" type='text/css' media='all' />

<!-- 複製提醒 -->
<script src="https://cdn.bootcss.com/sweetalert/1.1.3/sweetalert.min.js"></script>
<script>
  document.body.oncopy = function () {
    swal("複製成功 🎉",
            "若要轉載或引用請務必保留原文鏈接，並申明來源。如果你覺得本倉庫不錯，那就來 GitHub 給個 Star 吧 😊   - by 吳跟強",
            "success"); };
</script>

效果圖：

image-20200509114100528

4.8 添加網站運行時間

在 index.html 頁面中寫入：

<!-- 訪問量統計 -->
<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

<!-- 運行時間統計 -->
<script language=javascript>
  function siteTime() {
    window.setTimeout("siteTime()", 1000);
    var seconds = 1000;
    var minutes = seconds * 60;
    var hours = minutes * 60;
    var days = hours * 24;
    var years = days * 365;
    var today = new Date();
    var todayYear = today.getFullYear();
    var todayMonth = today.getMonth() + 1;
    var todayDate = today.getDate();
    var todayHour = today.getHours();
    var todayMinute = today.getMinutes();
    var todaySecond = today.getSeconds();
    /* Date.UTC() -- 返回date對象距世界標準時間(UTC)1970年1月1日午夜之間的毫秒數(時間戳)
    year - 作爲date對象的年份，爲4位年份值
    month - 0-11之間的整數，做爲date對象的月份
    day - 1-31之間的整數，做爲date對象的天數
    hours - 0(午夜24點)-23之間的整數，做爲date對象的小時數
    minutes - 0-59之間的整數，做爲date對象的分鐘數
    seconds - 0-59之間的整數，做爲date對象的秒數
    microseconds - 0-999之間的整數，做爲date對象的毫秒數 */
    var t1 = Date.UTC(2020, 02, 10, 00, 00, 00); //北京時間2020-02-10 00:00:00
    var t2 = Date.UTC(todayYear, todayMonth, todayDate, todayHour, todayMinute, todaySecond);
    var diff = t2 - t1;
    var diffYears = Math.floor(diff / years);
    var diffDays = Math.floor((diff / days) - diffYears * 365);
    var diffHours = Math.floor((diff - (diffYears * 365 + diffDays) * days) / hours);
    var diffMinutes = Math.floor((diff - (diffYears * 365 + diffDays) * days - diffHours * hours) / minutes);
    var diffSeconds = Math.floor((diff - (diffYears * 365 + diffDays) * days - diffHours * hours - diffMinutes * minutes) / seconds);
    document.getElementById("sitetime").innerHTML = " 本網站已運行 " + diffYears + " 年 " + diffDays + " 天 " + diffHours + " 小時 " + diffMinutes + " 分鐘 " + diffSeconds + " 秒 ";
  }
  siteTime();
</script>

然後嵌入代碼：

<span id="sitetime"></span>

如果和我一樣嵌入在頁腳部分，可以如圖設置：

image-20200518194213637

效果圖如下：

image-20200518194304281

4.9 美化提示樣式

Docsify-alerts

效果圖：

image-20200616123330739

（1）在 index.html 頁面中寫入：

<!-- Latest -->
<script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>

默認情況下，樣式 flat 和 callout（默認值：callout）和類型 NOTE，TIP，WARNING 和 DANGER 支持。在類型和標題之間使用以下映射：

Type Heading
NOTE Note
TIP Tip
WARNING Warning
DANGER Attention

如果想效果是這樣：

image-20200616124526081

可以在 index.html 頁面中添加：

<script>
  window.$docsify = {
    'flexible-alerts': {
      style: 'flat'
    }
  };
</script>

本人習慣這樣的格式，所以選擇默認：

image-20200616124707326

（3）使用示例：

  • 示例一：
> [!NOTE]
> An alert of type 'note' using global style 'callout'.

效果：

[!NOTE]
An alert of type ‘note’ using global style ‘callout’.

  • 示例二：
> [!TIP]
> An alert of type 'tip' using global style 'callout'.

效果：

[!TIP]
An alert of type ‘tip’ using global style ‘callout’.

  • 示例三：
> [!WARNING]
> An alert of type 'warning' using global style 'callout'.

效果：

[!WARNING]
An alert of type ‘warning’ using global style ‘callout’.

  • 示例四：
> [!DANGER]
> An alert of type 'danger' using global style 'callout'.

效果：

[!DANGER]
An alert of type ‘danger’ using global style ‘callout’.

  • 示例五：
> [!NOTE|style:flat]
> An alert of type 'note' using alert specific style 'flat' which overrides global style 'callout'.

效果：

[!NOTE|style:flat]
An alert of type ‘note’ using alert specific style ‘flat’ which overrides global style ‘callout’.

  • 示例六：
> [!TIP|style:flat|label:My own heading|iconVisibility:hidden]
> An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'.
> In addition, this alert uses an own heading and hides specific icon.

效果：

[!TIP|style:flat|label:My own heading|iconVisibility:hidden]
An alert of type ‘tip’ using alert specific style ‘flat’ which overrides global style ‘callout’.
In addition, this alert uses an own heading and hides specific icon.

（4）使用自定義類型 COMMENT

<script>
  window.$docsify = {
    'flexible-alerts': {
      comment: {
        label: "Comment",

        // localization
        label: {
          '/en-GB/': 'Comment',
          '/': 'Kommentar'
        },

        // Assuming that we use Font Awesome
        icon: "fas fa-comment",
        className: "info"
      }
    }
  };
</script>
  • 示例：
> [!COMMENT]
> An alert of type 'comment' using style 'callout' with default settings.

效果：

[!COMMENT]
An alert of type ‘comment’ using style ‘callout’ with default settings.

4.10 實現舊域名跳轉

在 index.html 頁面中寫入：

<!-- 舊域名跳轉 -->
<script>
    if (location.host != "notebook.js.org") {
        alert("本網站已遷移到新網址：notebook.js.org，請按確定前往新網址");
        window.location.href ="https://notebook.js.org/";
    }
</script>

效果：

image-20200616151626613

當然不能讓測試的地址出現跳轉啊，所以進行下面優化：

<!-- 舊域名跳轉 -->
<script>
    if (location.host != "notebook.js.org" && location.host != "127.0.0.1:3000") {
        alert('本站已遷移至新網址：notebook.js.org，請按"確定"鍵前往新網址');
        window.location.href ="https://notebook.js.org/";
    }
</script>

效果：

image-20200616152811411

4.11 Social Share 分享插件

經過測試，無法直接在 index.html 中嵌入代碼
需要先安裝上面的外鏈腳本插件：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>

後在 .md 文件中寫下：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/css/share.min.css">
<div class="social-share"></div>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/js/social-share.min.js"></script>

效果：

image-20200616203542784

4.12 右下角添加 live2d

效果圖：

image-20200620102427906

在 index.html 中添加：

<script src="https://eqcn.ajz.miesnfu.com/wp-content/plugins/wp-3d-pony/live2dw/lib/L2Dwidget.min.js"></script>
<script>
  L2Dwidget.init({
    "model": {
      //jsonpath控制顯示那個小蘿莉模型，
      //(切換模型需要改動)
      jsonPath: "https://unpkg.com/[email protected]/assets/koharu.model.json",
      "scale": 1
    },
    "display": {
      "position": "right", //看板孃的表現位置
      "width": 70,  //小蘿莉的寬度
      "height": 140, //小蘿莉的高度
      "hOffset": 35,
      "vOffset": -20
    },
    "mobile": {
      "show": true,
      "scale": 0.5
    },
    "react": {
      "opacityDefault": 0.7,
      "opacityOnHover": 0.2
    }
  });
</script>

即可。

當然你可以通過修改模型切換顯示不同的小蘿莉，以下是模型列表：

通過替換上面 jsonPath 中的 live2d-widget-model-koharu 來修改小蘿莉，

替換的小蘿莉效果可以參考這裏，點我（引用下大佬的鏈接，筆芯）

  • live2d-widget-model-chitose
  • live2d-widget-model-epsilon2_1
  • live2d-widget-model-gf
  • live2d-widget-model-haru/01 (use npm install --save live2d-widget-model-haru)
  • live2d-widget-model-haru/02 (use npm install --save live2d-widget-model-haru)
  • live2d-widget-model-haruto
  • live2d-widget-model-hibiki
  • live2d-widget-model-hijiki
  • live2d-widget-model-izumi
  • live2d-widget-model-koharu
  • live2d-widget-model-miku
  • live2d-widget-model-ni-j
  • live2d-widget-model-nico
  • live2d-widget-model-nietzsche
  • live2d-widget-model-nipsilon
  • live2d-widget-model-nito
  • live2d-widget-model-shizuku
  • live2d-widget-model-tororo
  • live2d-widget-model-tsumiki
  • live2d-widget-model-unitychan
  • live2d-widget-model-wanko
  • live2d-widget-model-z16

!> 另一個更強大一些，有 7 個模型，直接那旁邊的按鈕就可以切換，但是切換有點慢（第一個模型有 70+ 的衣服，其他模型沒試）

如果想體驗這種動態效果：

image-20200620103029451

僅僅需要在 index.html 中添加下面語句即可：

<script src="https://cdn.jsdelivr.net/gh/stevenjoezhang/live2d-widget/autoload.js"></script>

4.13 訪問量統計

在 index.html 中添加：

<!-- 訪問量統計 -->
<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

在想添加的 md 文件中添加：

<br>

<span id="busuanzi_container_site_pv" style='display:none'>
    👀 本站總訪問量：<span id="busuanzi_value_site_pv"></span> 次
</span>
<span id="busuanzi_container_site_uv" style='display:none'>
    | 🚴‍♂️ 本站總訪客數：<span id="busuanzi_value_site_uv"></span> 人
</span>

<br>

效果圖：

image-20200628125844906

發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

EnjoyToShare | 考研英語複試口語

英語面試和口語 文章目錄英語面試和口語前言面試始末從面試初始到結束的過程及細節面試過程中的相關問題回答面試過程中的宜與忌口語之自我介紹自我介紹（T+S）自我介紹（60s）自我介紹（90s）口語之自由問答自我認知類問答興趣特長性格特

吴跟强 2020-06-16 14:25:59

EnjoyToShare | 使用 youget 在電腦上下載bilibili的視頻

作者： wugenqiang 個人博客：https://wugenqiang.gitee.io 學習筆記：https://wugenqiang.gitee.io/cs-notes 簡單介紹 You-get是GitHub上

吴跟强 2020-06-16 14:25:59

EnjoyToShare | 加油，奮進的我們！

人生路，我們一起走！希望可以幫助到勤奮的你！ 博主筆記使用說明

吴跟强 2020-06-16 14:25:58

LaTex 語法使用指南

更新地址：LaTex 語法使用指南 LaTex 語法使用指南 💭 LaTex 中文介紹.pdf（全） 文章目錄LaTex 語法使用指南1 公式顯示位置1.1 行內公式1.2 行間公式2 數學符號2.1 上下標2.2 導數符號2.2

吴跟强 2020-06-16 14:25:58

EnjoyToShare | 考研資料分享羣

作者： wugenqiang 個人博客：https://wugenqiang.gitee.io 學習筆記：https://notebook.js.org/ 考研過程中會有很多資料需要學習，所以我建了一個QQ羣，方便資料的查看

吴跟强 2020-06-16 14:25:58

加油，奮進的我們！

吴跟强 2020-05-22 16:11:41

考研英語複試口語

吴跟强 2020-05-03 05:59:07

Docsify 創建文檔網站

吴跟强 2020-04-28 03:21:07

VuePress 創建文檔網站

吴跟强 2020-04-28 03:21:07

Docute 創建文檔網站（docute v3）

吴跟强 2020-04-25 19:03:11

金陵科技學院課程攻略共享計劃

吴跟强 2020-04-25 02:15:41

Typora+PicGo+Gitee實現圖片上傳功能

吴跟强 2020-04-21 09:56:31

EnjoyToShare | 考研英語複試口語

英語面試和口語 文章目錄英語面試和口語前言面試始末從面試初始到結束的過程及細節面試過程中的相關問題回答面試過程中的宜與忌口語之自我介紹自我介紹（T+S）自我介紹（60s）自我介紹（90s）口語之自由問答自我認知類問答興趣特長性格特

吴跟强 2020-06-16 14:25:59

EnjoyToShare | 使用 youget 在電腦上下載bilibili的視頻

作者： wugenqiang 個人博客：https://wugenqiang.gitee.io 學習筆記：https://wugenqiang.gitee.io/cs-notes 簡單介紹 You-get是GitHub上

吴跟强 2020-06-16 14:25:59

EnjoyToShare | 加油，奮進的我們！

人生路，我們一起走！希望可以幫助到勤奮的你！ 博主筆記使用說明

吴跟强 2020-06-16 14:25:58