插件沒有什么邏輯順序,大家可以按照目錄大綱直接定位到感興趣的插件部分閱讀即可.
更多插件正在陸續更新中,敬請期待...
最新更新插件
tbfed-pagefooter
版權頁腳插件gitalk
評論插件search-plus
中文搜索插件
gitalk
評論插件並不是gitbook
插件,因而集成方式和一般的插件安裝方式不同!
tbfed-pagefooter
版權頁腳插件
如果希望將網頁源碼暴露出去並接受公眾的監督校准的話,使用edit-link插件可以直接鏈接到源碼文件.
鏈接地址: https://plugins.gitbook.com/plugin/tbfed-pagefooter
激活插件配置
在 book.json
中配置 tbfed-pagefooter
插件,詳細說明請參考 tbfed-pagefooter 插件.
示例:
{
"plugins": ["tbfed-pagefooter"],
"pluginsConfig": {
"tbfed-pagefooter": {
"copyright":"© 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/plugin/disqus
激活插件配置
在 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/plugin/edit-link
激活插件配置
在 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/plugin/github
激活插件配置
在 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/plugin/search-plus
激活插件配置
在 book.json
中配置 github
插件,詳細說明請參考 github 插件.
示例:
{
"plugins": [
"-lunr",
"-search",
"search-plus"
]
}
安裝 search-plus
插件
示例:
$ gitbook install
測試 search-plus
插件
測試是否能夠進行中文搜索,如果不能,請確保已移除默認的 "lunr"
和 "search"
插件.
示例:
$ gitbook serve