gitbook 入門教程之實用外掛(新增3個外掛)

雪之夢技術驛站發表於2019-04-06

Git

外掛沒有什麼邏輯順序,大家可以按照目錄大綱直接定位到感興趣的外掛部分閱讀即可.

更多外掛正在陸續更新中,敬請期待...

`tbfed-pagefooter` 版權頁尾外掛

如果希望將網頁原始碼暴露出去並接受公眾的監督校準的話,使用edit-link外掛可以直接連結到原始碼檔案.

連結地址: plugins.gitbook.com/plugin/tbfe…

啟用外掛配置

在 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 外掛了.

連結地址: plugins.gitbook.com/plugin/disq…

啟用外掛配置

在 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外掛可以直接連結到原始碼檔案.

連結地址: plugins.gitbook.com/plugin/edit…

啟用外掛配置

在 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 指定倉庫.

連結地址: plugins.gitbook.com/plugin/gith…

啟用外掛配置

在 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 外掛.

連結地址: plugins.gitbook.com/plugin/sear…

啟用外掛配置

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

示例:

{
    "plugins": [
      "-lunr", 
      "-search", 
      "search-plus"
    ]
}
複製程式碼

安裝 `search-plus` 外掛

示例:

$ gitbook install
複製程式碼

測試 `search-plus` 外掛

測試是否能夠進行中文搜尋,如果不能,請確保已移除預設的 "lunr" 和 "search" 外掛.

示例:

$ gitbook serve
複製程式碼

gitbook 入門教程之主題外掛(初稿)
2019-04-09
Git
gitbook 入門教程之外掛介紹
2019-04-05
Git
Chrome外掛入門
2019-01-28
Chrome
Vim外掛入門
2014-09-28
開發者的實用 Vim 外掛（3）
2017-04-07
React實用外掛
2017-12-26
React
10個實用的Photoshop外掛
2013-11-05
Chrome外掛開發入門
2021-04-18
Chrome
[Vue] 外掛開發入門
2017-01-05
Vue
Qt入門（11）——Qt外掛
2014-09-30
QT
5款好用的開源JS圖片裁剪外掛(3個jQuery外掛，2個AngularJS外掛)
2016-03-08
JSjQueryAngular
[外掛擴充套件]qq登入外掛
2019-05-11
套件
Babel外掛開發入門指南
2018-06-03
Babel
Babel 外掛開發入門指南
2018-06-05
Babel
Java外掛開發入門示例
2009-08-13
Java
gitbook 入門教程之 gitbook 簡介
2019-03-30
Git
入門看看？Chrome外掛初窺與實踐
2020-02-29
Chrome
9個超實用jQuery/CSS3應用外掛欣賞
2015-03-18
jQueryCSSS3
8個超實用的jQuery外掛應用
2016-02-16
jQuery
15個超級實用的jQuery外掛
2014-09-26
jQuery
10個超實用jquery外掛資源
2012-06-05
jQuery
實用webpack外掛之DefinePlugin
2019-03-04
WebPlugin
webpack-bundle-analyzer外掛快速入門
2019-04-17
Web
前端圖表外掛ECharts入門教程
2020-12-09
前端Echarts
webpack4入門筆記——外掛
2018-05-09
Web筆記
jQuery入門筆記之（七）外掛
2016-03-03
jQuery筆記
小外掛大功能！輕量化森BIM外掛手把手教學
2022-05-12
微信登入外掛
2020-04-04
mybatis plus 新增分頁外掛
2024-03-26
MyBatis
8個針對開發者的MooTools實用外掛
2011-09-07
PHP外掛系統的實現(七):外掛案例
2021-06-15
PHP
[外掛擴充套件]書架外掛（新外掛後臺）
2019-05-11
套件
外掛檔案上傳外掛 ajaxfileupload.js外掛
2012-12-01
JS
mini-css-extract-plugin外掛快速入門
2019-04-19
CSSPlugin
Gradle外掛從入門到進階
2019-05-05
Gradle
babel外掛入門-AST（抽象語法樹）
2018-03-27
BabelAST抽象語法樹
jQ基礎篇–外掛開發入門
2017-03-08
Xcode6外掛開發入門
2015-05-09
XCode

gitbook 入門教程之實用外掛(新增3個外掛)

最新更新外掛

`tbfed-pagefooter` 版權頁尾外掛

啟用外掛配置

安裝 `tbfed-pagefooter` 外掛

測試 `tbfed-pagefooter` 外掛

`disqus` 評論外掛

註冊 `disqus.com` 賬號

註冊並繫結域名

選擇服務型別

安裝並配置 `disqus` 到網站

安裝並配置 `disqus` 外掛

啟用外掛配置

安裝 `disqus` 外掛

測試 `disqus` 外掛

`gitalk` 評論外掛

申請 GitHub Application 授權

安裝並整合到網站

測試整合效果

進一步思考

小結

`edit-link` 編輯連結外掛

啟用外掛配置

安裝 `edit-link` 外掛

測試 `edit-link` 外掛

`github` 外掛

啟用外掛配置

安裝 `github` 外掛

測試 `github` 外掛

`search-plus` 中文搜尋外掛

啟用外掛配置

安裝 `search-plus` 外掛

測試 `search-plus` 外掛

相關文章

gitbook 入門教程之實用外掛(新增3個外掛)

最新更新外掛

tbfed-pagefooter 版權頁尾外掛

啟用外掛配置

安裝 tbfed-pagefooter 外掛

測試 tbfed-pagefooter 外掛

disqus 評論外掛

註冊 disqus.com 賬號

註冊並繫結域名

選擇服務型別

安裝並配置 disqus 到網站

安裝並配置 disqus 外掛

啟用外掛配置

安裝 disqus 外掛

測試 disqus 外掛

gitalk 評論外掛

申請 GitHub Application 授權

安裝並整合到網站

測試整合效果

進一步思考

小結

edit-link 編輯連結外掛

啟用外掛配置

安裝 edit-link 外掛

測試 edit-link 外掛

github 外掛

啟用外掛配置

安裝 github 外掛

測試 github 外掛

search-plus 中文搜尋外掛

啟用外掛配置

安裝 search-plus 外掛

測試 search-plus 外掛

相關文章

`tbfed-pagefooter` 版權頁尾外掛

安裝 `tbfed-pagefooter` 外掛

測試 `tbfed-pagefooter` 外掛

`disqus` 評論外掛

註冊 `disqus.com` 賬號

安裝並配置 `disqus` 到網站

安裝並配置 `disqus` 外掛

安裝 `disqus` 外掛

測試 `disqus` 外掛

`gitalk` 評論外掛

`edit-link` 編輯連結外掛

安裝 `edit-link` 外掛

測試 `edit-link` 外掛

`github` 外掛

安裝 `github` 外掛

測試 `github` 外掛

`search-plus` 中文搜尋外掛

安裝 `search-plus` 外掛

測試 `search-plus` 外掛