莱姆狼🐺的小窝
目录

本文是基于个人从零实践经验，
简要介绍了笔者是如何使用giscus工具为本站中 .md .org 格式的文章挂载评论区。

This post is also available in: English

使用giscus为org-mode的Hugo博客文章建立评论区

1. giscus简介

giscus，一款基于Github Discussions的评论区系统，它与另一款基于Github Issues的评论区系统utterances极为神似。

giscus的作者laymonage (Sage Abdullahe)在其博客的Introducing giscus一文中提到：

Ta也曾是utterances的用户，直到Github推出discussions功能时，使用discussions替代issues作为评论区系统后端的想法应运而生。

Github方面在推出discussions时也曾这样说过：

"Until now, GitHub only offered issues and pull requests as places to have these conversations. But issues and pull requests both have a linear format—well suited for merging code, but not for creating a community knowledge base. Conversations need their own place —that’s what GitHub Discussions is for."

—— from New from Satellite 2020: GitHub Discussions, Codespaces, securing code in private repositories, and more

简言之，相较于Issues，Discussions更适合用来"discuss": "Conversations need their own place"

多说无益，在二者的主页下方就有功能展示，读者可以自行对比体验：
utteranc.es, giscus

2. 如何使用

根据giscus主页上的所需信息，不难归纳出使用giscus需要以下三个步骤：

  1. github仓库配置
  2. 生成嵌入代码
  3. 启用giscus

2.1 github仓库配置

giscus基于github仓库的discussions功能，所以我们需要一个仓库并开通discussions来作为其后端。你可以选择 新建一个全新的仓库 专用于网站评论区，或者像我一样 直接使用网站github仓库 。

⚠️注意：作为评论区后端的github仓库必须是 *Public/公开* 仓库

2.1.1 启用Github Discussions

被选为评论区后端的github仓库首页 -> setting选项卡 -> 左侧选择General -> 右侧Features栏目下 -> 勾选Discussions

2.1.2 安装giscus应用

进入到github.com/apps/giscus即可将giscus安装到指定的github仓库

2.2 生成嵌入代码

giscus主页提供了极为简洁易操作的代码生成流程，只需要用户填表即可得到所需的代码：

  1. 语言：我需要为博客中英文页面使用不同的评论区UI语言。
    所以手动修改 data-lang="zh-CN" 或 data-lang="en"
  2. 仓库：按格式填入指定仓库，页面会自动检测目标仓库是否符合要求，并获取所需信息用于生成代码。

  3. 映射关系：

    pathname
    以本文为例，将会是
    /posts/20230827-b49c5a4d/
    URL
    笔者没有测试过此项，可能会是
    blog.limewolf.top/posts/20230827-b49c5a4d/ 这样的格式吧
    <title>
    以本文为例，是
    使用giscus为org-mode的Hugo博客文章建立评论区 - 莱姆狼🐺的小窝
    og:title
    如果博客启用了Open Graph protocol，以本文为例，是
    使用giscus为org-mode的Hugo博客文章建立评论区
    特定字符串
    顾名思义，自定义特定字符串
    编号
    直接指定特定编号的discussion为评论区

    由于我希望同一篇文章的不同语言版本共用同一个评论区（同一话题，一起讨论，体验不割裂），所以我选择了使用 特定字符串 来映射discussion与giscus。
    例如，在本站的guestbook中，giscus代码中是这样配置的：

    data-mapping="specific"
data-term="Comment: guestbook"

    相关联的三个页面是这样的：
    访客留言版(guestbook中文页面)，guestbook英文页，github讨论区

  4. Discussion分类：正如作者所言，确保你的discussion不会被隔壁小朋友捣乱就请乖乖选择 announcements ，并勾选只匹配该分类。
  5. 特性：一些顾名思义的特性。

2.3 启用giscus

2.3.1 在markdown页面中启用

直接将giscus主页中生成的html代码放进你期望插入评论区的位置（例如文章末尾）即可。

2.3.2 在org-mode页面中启用

需要将html代码包含在 export html 中，像这样：（可以插入到文章任意位置）

#+BEGIN_EXPORT HTML
<script src="https://giscus.app/client.js"
        ......
        crossorigin="anonymous"
        async>
</script>
#+END_EXPORT
（tips: 插入export html的快捷键是 C-c C-, h）

Fin.

giscus的使用比我预想中简单太多太多，
我很快地就上手用它制作了访客留言版，
仅在将他嵌入到我的 .org 文章中时遇到了一点点的阻碍。

感谢强大的chatgpt协助我跨越阻碍

所以本文也并无更多细节可以描述，吧？
欢迎在评论区讨论和提问~

感谢giscus及其作者laymonage为本博客的互动性提供了关键的支持

感谢阅览！
:)