|
|
发表于 2022-9-27 12:12:28
|
显示全部楼层
使用GitHub Page 或者 Gitee Page搭建好静态网页博客之后，只有文章没有互动会显得很枯燥，但是需要评论功能就需要去撸业务代码，这样的成本未免太高。面对这种需求，Gittalk 横空出世，它利用Github Api 和 Github 仓库的 issue 功能，建立起了一套成熟的评论系统。Gitalk 是一个基于 Github Issue 和 Preact 开发的评论插件，它除了支持 Hexo 外，还支持我们所用的 Hugo，以及 Java、php 等语言开发的博客。
它拥有以下特性：
- 使用 GitHub 登录
- 支持多语言 [en, zh-CN, zh-TW, es-ES, fr, ru, de, pl, ko]
- 支持个人或组织
- 无干扰模式（设置 distractionFreeMode 为 true 开启）
- 快捷键提交评论 （cmd|ctrl + enter）
本文以 Hugo 为例，对插件的接入和中间踩过的坑进行介绍。
Gittalk接入
注册GithubApplication
首先需要注册 GitHub Application，链接如下：
https://github.com/settings/applications/new
我已经帮你将页面翻译成了中文版，如下图。
你需要填写Application name，起一个应用名；填写Homepage URL，也就是你的博客地址；填写Authorization callback URL，也就是回调地址，通常为你的博客地址。填写完成后，点击绿色按钮注册即可。
配置好之后会出现如下页面，点击Generate a new client secret生产新的密钥，Client ID和Client secret在后面config.toml 中配置时需要用到。
新增gitalk.html文件
引入评论插件这一步需要修改主题源码，之前的文章我们已经提到过如何拉取主题，这里就当大家已经做好了前期准备工作。
- 进入项目的根目录，
- 然后进入主题下的/layouts/partials文件夹
- 创建文件gitalk.html
cd themes/主题名/layouts/partials/touch gitalk.htmlvi gitalk.html
编辑创建好的gitalk.html文件，将以下内容插入。
{{ if .Site.Params.enableGitalk }}<div id="gitalk-container"></div><link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css"><script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script><script> const gitalk = new Gitalk({ clientID: '{{ .Site.Params.Gitalk.clientID }}', clientSecret: '{{ .Site.Params.Gitalk.clientSecret }}', repo: '{{ .Site.Params.Gitalk.repo }}', owner: '{{ .Site.Params.Gitalk.owner }}', admin: ['{{ .Site.Params.Gitalk.owner }}'], id: location.pathname, // Ensure uniqueness and length less than 50 distractionFreeMode: false // Facebook-like distraction free mode }); (function() { if (["localhost", "127.0.0.1"].indexOf(window.location.hostname) != -1) { document.getElementById('gitalk-container').innerHTML = 'Gitalk comments not available by default when the website is previewed locally.'; return; } gitalk.render('gitalk-container'); })();</script>{{ end }}
然后保存即可。
编辑single.html
需要编辑主题文件夹下的文件/_default/single，以引入Gittalk插件。不同的模板内容不一样，只要找到合适位置，比如content内容之后插入即可。{{ partial "gitalk.html" . }}这行代码的意思就是将之前定义的Html内容引入这个文件中，这是Hugo的语法。
vi ../_default/single.html ## 将下方内容插入{{ partial "gitalk.html" . }}
配置config.toml
最后一步便是配置toml文件（根目录下），因为之前的html中很多关键变量使用了表达式的形式，这就使我们可以利用配置文件灵活更改。
[params] enableGitalk = true[params.gitalk] clientID = "Client ID" # 您刚才创建Github Application 的 Client ID clientSecret = "Client Secret" # 您刚才创建Github Application 的 Client Secret repo = "xxxx.github.io" # 您的博客的github地址Repository name，例如：xxxx.github.io owner = "GitHub ID" # 您的GitHub ID admin= "GitHub ID" # 您的GitHub ID id= "location.pathname" # 文章页面的链接地址就是ID labels= "gitalk" # Github issue labels. If you used to use Gitment, you can change it perPage= 15 # Pagination size, with maximum 100. pagerDirection= "last" # Comment sorting direction, available values are 'last' and 'first'. createIssueManually= true # 设置为true，如果是管理员登录，会自动创建issue，如果是false，需要管理员手动添加第一个评论(issue) distractionFreeMode= false # Enable hot key (cmd|ctrl + enter) submit comment.
Gittalk 是根据文章的地址进行issue设置并匹配的，所以文章地址不要轻易变更。
编译上传
配置好上述流程后，本地编译源码让那会提交到GitHub。如果你已经按照上一篇文章的方式使用了GitHub Actions，那么直接提交源码即可。如果 createIssueManually 设置是 true ，首次登录后 Gitalk 就能正常使用，否则需要登录后，发起一个首论，才能正常使用。效果如下：
踩坑指南
在搭建评论系统的过程中可能遇到很多问题，有些问题并不好解决，这里把我踩的坑汇总了一下，节约你的时间。
1.插件无法加载
如果你按照上述步骤全部配置正确，但是页面与之前没有区别，也没用报错，出现这种情况有如下解决办法：
- 没有刷新浏览器缓存，重新刷新即可
- 网络原因，GitHub 访问不稳定，检查你是否能正常访问GitHub，或者打开VPN重试。
通常在没有报错的情况下，插件是引用成功的，多刷新尝试即可。
2.404 Error: Not Found
当出现404 Error: Not Found这个报错的时候，意味着插件引入成功，但是有些配置上的小问题。
没能顺利找到你的仓库，检查config.toml文件关于仓库的配置内容。
#params.gitalkrepo = "rep名字" # 你的GitHub托管仓库
修改完之后你可以通过下面的链接直接检查，如果配置正确会返回数据。
https://api.github.com/repos/owner名字/repo名称/issues?labels=Gitalk,...
3.Error: Validation Failed
当出现Error: Validation Failed.报错，是因为 GitHub 对 Issue 的 label 存在限制，不能超过 50 个字符，否则会导致加载 Gitalk 插件失败。而我们在html中定义的页面id默认取的就是文章页面的链接地址，通常情况下50个字符是够的，但是如果用中文给文件命名那么中文字符编码之后长度就很容易超过限制。
所以，解决方案如下：
- 用英文或者数字代替中文命名markdown文件
- 截取路径字符串的一部分作为url
- 对中文标题使用MD5编码
截取路径字符串
修改之前的Html文件，加入以下代码，只截取路径的前50个字符作为id。
var title = location.pathname.substr(0, 50); var gitalk = new Gitalk({ clientID: 'xxxx', clientSecret: 'xxxx', repo: 'xxxx', owner: 'xxxx', admin: ['xxxx'], id: title, distractionFreeMode: false })
MD5编码
使用MD5函数对原有的路径名进行编码，依旧是修改html文件。
{% if page.comments && theme.gitalk.enable %} <link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css"> <script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script> <script src="https://rawgit.com/qhh0205/78e9e0b1f3114db6737f3ed8cdd51d3a/raw/3894c5be5aa2378336b1f5ee0f296fa0b22d06e9/md5.min.js"></script> <script type="text/javascript"> var gitalk = new Gitalk({ clientID: 'xxxx', clientSecret: 'xxxx', repo: '{{ xxxx }}', owner: '{{ xxxx }}', admin: ['{{ xxxx}}'], id: md5(location.pathname), distractionFreeMode: '{{ theme.gitalk.distractionFreeMode }}' }) gitalk.render('gitalk-container') </script>{% endif %} |
|
