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

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

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

最新更新插件

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

gitalk 評論插件並不是 gitbook 插件,因而集成方式和一般的插件安裝方式不同!

tbfed-pagefooter 版權頁腳插件

如果希望將網頁源碼暴露出去並接受公眾的監督校準的話,使用edit-link插件可以直接鏈接到源碼文件.

鏈接地址: https://plugins.gitbook.com/plugin/tbfed-pagefooter

gitbook-plugin-tbfed-pagefooter-preview.png

激活插件配置

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

示例:

安裝 tbfed-pagefooter 插件

示例:

$ gitbook install

測試 tbfed-pagefooter 插件

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

功能慎用: 如果文檔頻繁更新適合生成最後更新時間,如果長時間不更新文檔,豈不是最後更新時間還是幾年前,給讀者的感覺像是不再維護了一樣!

示例:

$ gitbook serve

gitbook-plugin-tbfed-pagefooter-preview.png

disqus 評論插件

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

gitbook-plugin-disqus-success-with-FQ.png

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

註冊 disqus.com 賬號

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

gitbook-plugin-disqus-preview.png

註冊並綁定域名

如果沒有註冊賬號請先註冊,否則直接登錄,當然也支持第三方賬號登錄(我使用的是谷歌賬號).

gitbook-plugin-disqus-login.png

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

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

gitbook-plugin-disqus-goal.png

接下來設置網站的相關信息,其中

gitbook-plugin-disqus-create-site.png

選擇服務類型

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

每個版本計劃有不同的收費標準以及相應的服務,可以根據實際情況選擇適合自己的服務類型.

gitbook-plugin-disqus-select-plan.png

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

gitbook-plugin-disqus-free-selected.png

安裝並配置 disqus 到網站

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

gitbook-plugin-disqus-install-website.png

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

gitbook-plugin-disqus-config-site.png

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

gitbook-plugin-disqus-complete.png

安裝並配置 disqus 插件

上一步我們已經獲取到唯一的標識: snowdreams1006 ,接下來可以繼續配置 disqus插件了.

鏈接地址: https://plugins.gitbook.com/plugin/disqus

激活插件配置

在 book.json 中配置 disqus 插件,根據實際情況修改成自己的縮寫名稱(shortName).

示例:

安裝 disqus 插件

示例:

$ gitbook install
 

測試 disqus 插件

示例:

$ gitbook serve

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

gitbook-plugin-disqus-success-with-FQ.png

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

gitbook-plugin-disqus-success-without-FQ.png

gitalk 評論插件

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

上述 disqus 評論插件雖然比較好用,但是註冊是在 disqus.com 官網,需要特殊手段才能訪問,即便成功配置了國內一般也是訪問不到的,因此功能相當雞肋.

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

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

gitbook-plugin-gitalk-preview.png

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

好了,現在讓我們開始集成到我們自己的項目中,遇到新鮮事物,當然先要參考官網介紹了.

申請 GitHub Application 授權

登錄 github 賬號,點擊 在線申請 授權應用.

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

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

比如第三方應用提供微信登錄,走的也是 OAuth 協議,這裡的第三方應用當然就是現在說的 Gitalk

插件,微信就是我們的 github .

新建應用,首頁 url 和授權回調 url 填寫相同的首頁鏈接即可,其他情況自定義填寫.

gitbook-plugin-gitalk-register-application.png

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

gitbook-plugin-gitalk-generate-token.png

安裝並集成到網站

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

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

稍微解釋下參數的含義:

• "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 ,體驗下集成效果.

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

示例:

上述參數僅供參考,實際使用中請替換成自己的配置,不然你也沒有我倉庫的權限,肯定會報錯的啊!

gitbook-plugin-gitalk-init-issue.png

心心相念的 gitalk 評論區呢?是不是哪裡配置錯了,為啥沒有出來?

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

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

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

gitbook-plugin-gitalk-index-success.png

終於集成了評論功能,而且還支持 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 插件開發文檔,目標鎖定在 index.js .

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

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

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

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

至此,之後再本地構建電子書時(gitbook build),gitbook-plugin-tbfed-pagefooter 自然會順便幫我們運行集成 gitalk 的相關代碼,這才是相對來說比較優雅的做法.

當然也不一定非要藉助 gitbook-plugin-tbfed-pagefooter 插件幫忙,也可以藉助別的插件進行集成,甚至自己寫個更好的插件.

小結

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

因此,通過 gitbook 插件開發的方式,在源碼文件輸出為目標文件時加入相關集成代碼,相當於手寫100條輸出語句和循環寫100條輸出語句.

其實本質上並沒有改變什麼,仍然是集成到每個頁面中,但是簡化了人工操作的工作量就是效率的提升.

如果有更高效更優雅的集成方式,歡迎大家一起探討.

如果希望將網頁源碼暴露出去並接受公眾的監督校準的話,使用edit-link插件可以直接鏈接到源碼文件.

鏈接地址: https://plugins.gitbook.com/plugin/edit-link

gitbook-plugin-edit-link-preview.gif

激活插件配置

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

示例:

安裝 edit-link 插件

示例:

$ gitbook install

測試 edit-link 插件

如果不能正常跳轉到源碼文件,多次試驗後重新更改 edit-link.base 節點內容,重新 gitbook serve 即可正常跳轉源碼文件.

示例:

$ gitbook serve

gitbook-plugin-edit-link-preview.png

github 插件

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

鏈接地址: https://plugins.gitbook.com/plugin/github

gitbook-plugin-github-preview.png

激活插件配置

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

示例:

安裝 github 插件

示例:

$ gitbook install

測試 github 插件

示例:

$ gitbook serve

gitbook-plugin-github-preview.png

search-plus 中文搜索插件

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

鏈接地址: https://plugins.gitbook.com/plugin/search-plus

gitbook-plugin-search-plus-preview.png

激活插件配置

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

示例:

安裝 search-plus 插件

示例:

$ gitbook install

測試 search-plus 插件

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

示例:

$ gitbook serve

gitbook-plugin-search-plus-preview.png

閱讀更多 雪之夢技術驛站 的文章

關鍵字: 敬請期待 版權頁 Google