gitbook 入門教程之實用插件(新增3個插件)

插件沒有什麼邏輯順序,你們能夠按照目錄大綱直接定位到感興趣的插件部分閱讀便可.

更多插件正在陸續更新中,敬請期待...

最新更新插件

• tbfed-pagefooter 版權頁腳插件
• gitalk 評論插件
• search-plus 中文搜索插件

gitalk 評論插件並非 gitbook 插件,於是集成方式和通常的插件安裝方式不一樣!

tbfed-pagefooter 版權頁腳插件

若是但願將網頁源碼暴露出去並接受公衆的監督校準的話,使用edit-link插件能夠直接連接到源碼文件.

連接地址: https://plugins.gitbook.com/p...

激活插件配置

在 book.json 中配置 tbfed-pagefooter 插件,詳細說明請參考 tbfed-pagefooter 插件.

示例:

{
    "plugins": ["tbfed-pagefooter"],
    "pluginsConfig": {
        "tbfed-pagefooter": {
          "copyright":"&copy snowdreams1006",
          "modify_label": "文件修訂時間：",
          "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

安裝 tbfed-pagefooter 插件

示例:

$ gitbook install

測試 tbfed-pagefooter 插件

啓動本地服務後,每一個頁面的頁腳處都會自動生成版權信息以及當前文件的最後更新時間.

功能慎用: 若是文檔頻繁更新適合生成最後更新時間,若是長時間不更新文檔,豈不是最後更新時間仍是幾年前,給讀者的感受像是再也不維護了同樣!

示例:

$ gitbook serve

disqus 評論插件

discus 是一款集成評論的插件,能夠爲靜態網站添加動態評論,讓你的網站動起來!

遺憾的是, discus 插件只有 FQ 才能正常使用,暫時沒找到其餘較好的替代方案.

註冊 disqus.com 帳號

gitbook 集成 disqus 插件中最重要的配置項就是註冊 disqus.com 網站惟一標識.

註冊並綁定域名

若是沒有註冊帳號請先註冊,不然直接登陸,固然也支持第三方帳號登陸(我使用的是谷歌帳號).

人機驗證時,選出符合條件的所有圖形,直到沒有新的圖形爲止,這一點和國內的靜態圖片驗證是不一樣的!

選擇安裝 disqus 插件(I want to install Disqus on my site ),接下來會綁定集成網站的域名.

接下來設置網站的相關信息,其中網站名稱(snodreams1006)是惟一標示,接下來集成到 gitbook 用的就是這個簡短名稱,而分類和語言按照實際狀況選擇便可.

選擇服務類型

disqus 網站提供的服務類型,有基礎班(basic),增強版(plus),專業版(pro)和免費版(free).

每一個版本計劃有不一樣的收費標準以及相應的服務,能夠根據實際狀況選擇適合本身的服務類型.

接下來以避免費版爲例進行有關演示

安裝並配置 disqus 到網站

估計是這些網站提供了默認的集成方式,這裏並沒看到 gitbook 相關的網站,所以選擇最後一個自定義網站.

填寫網站的基本信息,其中網站縮寫名稱仍然是 snowdreams1006,網址填寫 https://snowdreams1006.github.io/ ,至於其餘信息根據實際狀況填寫便可.

至此 disqus.com 網站配置完成,接下來咱們配置 gitbook 集成 disqus 插件.

安裝並配置 disqus 插件

上一步咱們已經獲取到惟一的標識: snowdreams1006 ,接下來能夠繼續配置 disqus 插件了.

連接地址: https://plugins.gitbook.com/p...

激活插件配置

在 book.json 中配置 disqus 插件,根據實際狀況修改爲本身的縮寫名稱(shortName).

示例:

{
    "plugins": ["disqus"],
    "pluginsConfig": {
        "disqus": {
            "shortName": "snowdreams1006"
        }
    }
}

安裝 disqus 插件

示例:

$ gitbook install

測試 disqus 插件

示例:

$ gitbook serve

正常狀況下(FQ),disqus 插件已經成功集成到 gitbook 網站了,所以推送到實際服務器上時看到的效果是這樣的.

若是你不具有條件(FQ),那麼你看到的仍然是這樣的.

gitalk 評論插件

本篇文章發表在開源中國後獲得網友 @八一菜刀 的評論,讓我推薦了gitalk 評論插件,初始使用了一下,確實不錯,所以在這裏更新下.

上述 disqus 評論插件雖然比較好用,可是註冊是在 disqus.com 官網,須要特殊手段才能訪問,即使成功配置了國內通常也是訪問不到的,所以功能至關雞肋.

gitalk 評論插件解決了這一痛點,利用 github 的開發者接口受權,將討論區的 issue 變成評論區,和 github 結合的如此緊密,適合用源碼託管到 github 這類狀況.

先混個臉熟,看一下 gitalk 官網 是如何介紹本身的呢.

看着效果確實不錯,而且評論區的內容直接做爲 github 倉庫的 issue,這麼好的想法我咋沒想到呢!

好了,如今讓咱們開始集成到咱們本身的項目中,遇到新鮮事物,固然先要參考官網介紹了.

申請 GitHub Application 受權

登陸 github 帳號,點擊 在線申請 受權應用.

看到這一步,想必讀者已經有個大概印象了,gitalk 插件是利用 github 的開發者服務,進行受權進而調用 issue 相關接口從而顯示評論功能.

這種由官網提供的開發者服務仍是比較好的,至少感受比手動模擬提交要靠譜些,更況且走的是 OAuth 受權模式.

好比第三方應用提供微信登陸,走的也是 OAuth 協議,這裏的第三方應用固然就是如今說的 Gitalk
插件,微信就是咱們的 github .

新建應用,首頁 url 和受權回調 url 填寫相同的首頁連接便可,其餘狀況自定義填寫.

應用登記成功後會生成 token 令牌,clientId 和 clientSecret 須要重點保存下來,待會須要用到.

安裝並集成到網站

在須要添加評論的頁面,添加下述內容引入 gitalk 插件,其中參數來自咱們上一步獲取的 clientId 和 clientSecret .

默認應該添加到 .html 頁面,固然也能夠添加到 .md 頁面,畢竟 markdown 語法也支持 html 標籤.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>
var gitalk = new Gitalk({
  "clientID": "clientId",
  "clientSecret": "clientSecret",
  "repo": "GitHub repo",
  "owner": "GitHub repo owner",
  "admin": ["GitHub repo admin"],
  "id": location.pathname,      
  "distractionFreeMode": false  
});
gitalk.render("gitalk-container");

稍微解釋下參數的含義:

• "clientID" : [必選] GitHub Application Client ID
• "clientSecret" : [必選] GitHub Application Client Secret
• "repo" : [必選] GitHub repository
• "owner" : [必選] GitHub repository 全部者，能夠是我的或者組織
• "admin" : [必選] GitHub repository 的全部者和合做者 (對這個 repository有寫權限的用戶)
• "id" : [可選] 頁面的惟一標識,默認值: location.href, 長度必須小於50,不然會報錯!
• "distractionFreeMode": [可選] 相似 Facebook 評論框的全屏遮罩效果,默認值: false

上述配置只是最簡配置,若是想要了解更多高級配置,請參考 官方文檔

測試集成效果

按照上述安裝步驟,將代碼複製到首頁(README.md)文件中,而後推送到 github ,體驗下集成效果.

注意: 這裏必須推送到服務器,由於申請應用時填寫的域名是線上地址,於是本地測試是不會成功的,會報錯,這一點和微信支付的回調地址相似.

示例:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>
var gitalk = new Gitalk({
  "clientID": "3f62415a283d19cbd696",
  "clientSecret": "aed0e1db0620bf5d0e3a3f0225f801997ad74e58",
  "repo": "snowdreams1006.github.io",
  "owner": "snowdreams1006",
  "admin": ["snowdreams1006"],
  "id": location.pathname,      
  "distractionFreeMode": false  
});
gitalk.render("gitalk-container");

上述參數僅供參考,實際使用中請替換成本身的配置,否則你也沒有我倉庫的權限,確定會報錯的啊!

心心相念的 gitalk 評論區呢?是否是哪裏配置錯了,爲啥沒有出來?

別急,要淡定,看一下提示說"未找到的 Issue 進行評論,請聯繫 @snowdreams1006 初始化建立",既然如此,那咱們就操做一下吧!

點擊下方的按鈕 使用 Github登陸 ,會跳轉到相應的倉庫,而後按照提示肯定.

再次返回首頁,刷新一下看看發生什麼神奇的事情了?

終於集成了評論功能,並且還支持 markdown 格式的評論呢!

進一步思考

確實不錯,心中天然是欣喜萬分,但別高興太早了,由於你會發現其餘頁面並無評論區,也很好理解,咱們目前僅僅在首頁(README.md) 集成了 gitalk 插件,也就是說使用 gitbook build 輸出的 index.html 首頁才支持評論區,其餘頁面沒有插入上述代碼,天然是沒有評論區功能的啊!

那若是想要實現全網站的全部頁面都集成評論區功能,應該怎麼辦呢?

百度搜索了一下,並無找到優雅的解決方案,若是有人可以提供更好的解決方案,還望不吝賜教,在此謝過.

既然網上找不到優雅的解決方案,那尋求專業人士的幫助也是一種好辦法,我去哪找 gitalk 的使用者呢?

聰明的你或許已經想到了,解鈴還須繫鈴人,固然是向推薦給我插件的大牛提問了!

他確實提供了一種思路,如下是網友@八一菜刀原話:

文檔裏面我用的是tbfed-pagefooter插件，不過我是在本地使用gitbook install後重寫了該插件的js，無非就是在js裏面加一段Gitalk的調用代碼，這樣使用gitbook build命令的時候，全部的頁面都會有Gitalk的評論調用

人家既然已經提供了思路,不太好意思繼續麻煩人家要源碼,既然如此,那就本身動手吧!

tbfed-pagefooter 插件很熟悉,通常是用於註明版權以及文章的修訂時間的,並且做用於每一個頁面,這一點就知足了集成 gitalk 相關代碼的基本要求.

大致方向肯定後,目前就是解決如何在 tbfed-pagefooter 插件構建的相關生命週期內順便執行咱們的代碼?

正常當前項目安裝 tbfed-pagefooter 插件後應該存放於 /node_modules/gitbook-plugin-tbfed-pagefooter 目錄,大體看一下插件的項目結構.

gitbook-plugin-tbfed-pagefooter
├── LICENSE
├── README.md
├── assets
│   └── footer.css
├── index.js
└── package.json

1 directory, 5 files
$

爲了基本看懂項目文件做用,特地去看了下 gitbook 插件開發文檔,目標鎖定在 index.js .

截取重要片斷,原來是電子書構建前動態增長了 html 片斷啊,這就好辦了!

hooks: {
    'page:before': function(page) {
      var _label = '最後更新時間: ',
          _format = 'YYYY-MM-DD',
          _copy = 'powered by snowdreams1006'
      if(this.options.pluginsConfig['tbfed-pagefooter']) {
        _label = this.options.pluginsConfig['tbfed-pagefooter']['modify_label'] || _label;
        _format = this.options.pluginsConfig['tbfed-pagefooter']['modify_format'] || _format;

        var _c = this.options.pluginsConfig['tbfed-pagefooter']['copyright'];
        _copy = _c ? _c + ' all right reserved，' + _copy : _copy;
      }
      var _copy = '<span class="copyright">'+_copy+'</span>'
      var str = ' \n\n<footer class="page-footer">' + _copy +
        '<span class="footer-modification">' +
        _label +
        '\n{{file.mtime | date("' + _format +
        '")}}\n</span></footer>'

      str += '\n\n<link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">'+
      '\n\n<script src="https://unpkg.com/gitalk@latest/dist/gitalk.min.js"></script>'+
      '\n\n<div id="gitalk-container"></div>'+
      '\n\n<script src="https://snowdreams1006.github.io/gitalk-config.js"></script>';

      page.content = page.content + str;
      return page;
    }
  },

看懂基本原理後順便修改了版權說明以及修訂時間格式,而後追加了集成 gitalk 的相關代碼.

這裏爲了方便修改 gitalk 配置,特地將相關配置項單獨託管到 github 專門的 gitalk-config.js 文件.

至於配置文件的內容,並沒什麼特殊之處,仍是順便貼一下吧!

var gitalk = new Gitalk({
  "clientID": "3f62415a283d19cbd696",
  "clientSecret": "aed0e1db0620bf5d0e3a3f0225f801997ad74e58",
  "repo": "snowdreams1006.github.io",
  "owner": "snowdreams1006",
  "admin": ["snowdreams1006"],
  "id": window.location.pathname,
  "distractionFreeMode": false
});
gitalk.render("gitalk-container");

至此,以後再本地構建電子書時(gitbook build),gitbook-plugin-tbfed-pagefooter 天然會順便幫咱們運行集成 gitalk 的相關代碼,這纔是相對來講比較優雅的作法.

固然也不必定非要藉助 gitbook-plugin-tbfed-pagefooter 插件幫忙,也能夠藉助別的插件進行集成,甚至本身寫個更好的插件.

小結

gitalk 插件相對 disqus 插件來講,更符合基本國情,只不過默認的集成方式只能一個頁面一個頁面去集成,當數量比較多時,工做量不敢想象.

所以,經過 gitbook 插件開發的方式,在源碼文件輸出爲目標文件時加入相關集成代碼,至關於手寫100條輸出語句和循環寫100條輸出語句.

其實本質上並無改變什麼,仍然是集成到每一個頁面中,可是簡化了人工操做的工做量就是效率的提高.

若是有更高效更優雅的集成方式,歡迎你們一塊兒探討.

edit-link 編輯連接插件

若是但願將網頁源碼暴露出去並接受公衆的監督校準的話,使用edit-link插件能夠直接連接到源碼文件.

連接地址: https://plugins.gitbook.com/p...

激活插件配置

在 book.json 中配置 edit-link 插件,詳細說明請參考 edit-link 插件.

示例:

{
    "plugins": ["edit-link"],
    "pluginsConfig": {
        "edit-link": {
          "base": "https://github.com/snowdreams1006/snowdreams1006.github.io/blob/master",
          "label": "編輯本頁"
        }
    }
}

安裝 edit-link 插件

示例:

$ gitbook install

測試 edit-link 插件

若是不能正常跳轉到源碼文件,屢次試驗後從新更改 edit-link.base 節點內容,從新 gitbook serve 便可正常跳轉源碼文件.

示例:

$ gitbook serve

github 插件

添加 github 圖標連接,方便直接跳轉到 github 指定倉庫.

連接地址: https://plugins.gitbook.com/p...

激活插件配置

在 book.json 中配置 github 插件,詳細說明請參考 github 插件.

示例:

{
    "plugins": ["github"],
    "pluginsConfig": {
        "github": {
          "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"
        }
    }
}

安裝 github 插件

示例:

$ gitbook install

測試 github 插件

示例:

$ gitbook serve

search-plus 中文搜索插件

默認的 search 搜索插件是不支持中文搜索的,而 search-plus 則功能更強大些,二者不能共存,須要禁用或移除 search 插件.

連接地址: https://plugins.gitbook.com/p...

激活插件配置

在 book.json 中配置 github 插件,詳細說明請參考 github 插件.

示例:

{
    "plugins": [
      "-lunr", 
      "-search", 
      "search-plus"
    ]
}

安裝 search-plus 插件

示例:

$ gitbook install

測試 search-plus 插件

測試是否可以進行中文搜索,若是不能,請確保已移除默認的 "lunr" 和 "search" 插件.

示例:

$ gitbook serve