免費好用的博客評論系統(tǒng)插件 -- utterances

關注我時間長點的讀者，都知道我除了維護一個個人技術博客之外，還有寫過很多實用的在線文檔。

這些文檔，都有一個痛病，他們都是靜態(tài)網站，因此沒有評論區(qū)。

而對于博客來說，評論區(qū)是增強技術交流的一個重要工具，文檔若有事實錯誤和描述性問題，讀者就沒法方便地向我反饋。

對于動態(tài)網站來說，可以動手設計一個評論管理系統(tǒng)，雖然可以做，但也并不是一件易事，要做用戶的管理（包括注冊、登陸），庫表的設計、多級回復等等

而靜態(tài)網站沒有數據庫，若想提供評論功能，通常的做法是直接使用現成的評論插件，界面美觀還易用。

# 1. 評論系統(tǒng)調研

我了解過的評論系統(tǒng)有：

• 國內：有言（官網已經掛了）、暢言（搜狐出品）

• 國外：Disqus（被墻）、gitment、gitalk、來比力（速度很慢）

其中 gitment 和 gitalk 的原理類似，都是將評論內容存儲在 github 倉庫的 issue 中。

我挑了知名度較高的 gitalk 部署了下，當我訪問文檔時，才發(fā)現這貨居然，要我手動為每篇文章倉庫一個 issue？

這對于一個還沒有多少文章的新站點來說，可能還不是什么問題，可是我的 5、6 年的文章，有上千篇，一個一個去手動創(chuàng)建，這是不可能的。

于是我就開始找自動化腳本，其中有 ruby 的，python 的，方案特別多，看得我眼花繚亂的。

最終在某個 Python 腳本作者的方案中，看到了這么一句話

好家伙，剛部署完一個，又讓我部署另一個。

不過 utterances 不用自動為每篇文章創(chuàng)建 issue，這個正是我需要的。

因此本篇文章是基于 utterances 插件的評論系統(tǒng)接入 Sphinx 文檔的教程

若你之前有跟著我的教程搭建過 Sphinx 在線技術文檔，可以跟著操作一下，因為我搜索了下，本篇應該是第一篇有公開的 Sphinx 接入 utterances評論系統(tǒng)的教程（也許有人使用過，但沒人分享過文章）。

# 2. 安裝 utterances

訪問 utterances 應用程序 ，然后點擊 Install 按鈕進行安裝

在安裝時，可以立即選擇是否限制其訪問的倉庫，若安裝時忘記設置了，也可以在安裝后再次選擇。

只要再次訪問 utterances 應用程序，就會顯示配置的界面

點進去就能更新配置，選擇完直接 Save 。

# 3. 定義評論模板

我的文檔使用的是 Sphinx + rtd 主題，因此找到 sphinx_rtd_theme 所在的目錄，比如我的目錄是 /usr/local/lib/python3.6/site-packages/sphinx_rtd_theme

在該目錄下新建 comments.html 文件，內容如下

<comments>
??<script?src="https://utteranc.es/client.js"
????repo="iswbm/magic-python"
????issue-term="pathname"
????theme="github-light"
????crossorigin="anonymous"
????async>
??script>
comments>

其中你需要根據自己的情況進行調整的字段只有 repo，填寫你評論要存放在哪個 github 倉庫。

定義了 comments 的模板文件后，要在 layout.html 中引用它

但由于原先 layout.html 已經預留了 comments 的內容，先將其刪除

替換成

?????????<div?class="articleComments">
???????????????{%?include?"comments.html"?%}
???????????div>

# 4. 編譯查看效果

執(zhí)行 make html 重新編譯文檔的靜態(tài) html 文件，再次查看網頁，就會發(fā)現在文檔的尾部出現了期待的評論區(qū)

想要在文章下評論，就得先登陸 Github 授權一下

登陸并授權之后，你的 Github 頭像出現了，是可以評論的狀態(tài)

utterances 的評論是放在 issue 里的，因此評論這邊也是要支持 markdown

寫完之后國，點下預覽可以看下效果

沒什么問題的話，可以點擊 comment 發(fā)送評論

評論就會出現在上方，這個布局有點迷呆，怎么不是在下方？

去 Github 倉庫的 issue 上看，確實是多了一條信息

# 5. 總結一下

utterances 與 gitalk 對比一下，缺點不少，比如：

• gitalk 可以通過 如下容器定義評論區(qū)的位置，而 utterances 則不行（反正我沒有找到對應方法），需要你有動手能力去定義模板。

• utterances 不支持在評論區(qū)直接引用他人的評論進行多級回復

• 當有評論時 utterances 的評論框是在所有的評論的下方，不太符合用戶邏輯

即使 utterances 有如此之多的缺點，但 utterances 不需要手動去創(chuàng)建 issue ，僅憑這一點，在我看來，就可以秒殺 gitalk ，希望 gitalk 早日改進支持吧。

現在我的六個在線文檔，都已經加上 utterances，大家在查閱學習時，若有問題可以在評論區(qū)提出來噢：

1、Python 黑魔法手冊：https://magic.iswbm.com
2、Python 中文指南：https://python.iswbm.com
3、PyCharm 中文指南：https://pycharm.iswbm.com
4、Go 編程時光：https://golang.iswbm.com
5、大白話 K8S（圖解 K8S）：https://k8s.iswbm.com
6、Go語言面試寶典：https://go-interview.iswbm.com

? ?

???