由 GitHub Discussions 驱动的评论系统。让访客借助 GitHub 在你的网站上留下评论和反应吧!本项目受 utterances 强烈启发。
注意: giscus 仍处于活跃开发中。GitHub 也还在活跃地开发 Discussions 及其 API。因此,一些 giscus 的特性可能随时间损坏或改变。
giscus 加载时,会使用 GitHub Discussions 搜索 API 根据选定的映射方式(如 URL、pathname、<title> 等)来查找与当前页面关联的 discussion。如果找不到匹配的 discussion,giscus bot 就会在第一次有人留下评论或回应时自动创建一个 discussion。
pathname
<title>
要评论,访客必须按 GitHub OAuth 流程授权 giscus app 代表他发帖。或者访客也可以直接在 GitHub Discussion 里评论。你可以在 GitHub 上管理评论。
选择 giscus 的显示语言。找不到你的语言?贡献一个吧。
选择 giscus 连接到的仓库。请确保:
一个公开的(public) GitHub 仓库。Discussion 将被连接到此仓库。
选择页面与嵌入的 discussion 之间的映射关系。
giscus 将查找标题中包含页面 URL 的 pathname 成分的 discussion。
URL
giscus 将查找标题中包含页面 URL 的 discussion。
giscus 将查找标题中包含页面的 <title> 标签的 discussion。
og:title
giscus 将查找标题中包含页面的 <meta property="og:title"> 标签的 discussion。
<meta property="og:title">
giscus 将查找标题中包含特定字符串的 discussion。
giscus 将按编号加载特定的 discussion。此选项不支持自动创建 discussion。
当有多个具有相似标题的讨论时,避免由于 GitHub 的模糊搜索方法而导致的不匹配。查看文档获取更多细节。
选择新 discussions 所在的分类。 推荐使用公告(announcements)类型的分类,以确保新 discussion 只能由仓库维护者和 giscus 创建。
当搜索匹配的 discussion 时,giscus 将只搜索该分类。
选择是否启用某些特性。
Discussion 的主帖子上的反应将会显示在评论前。
Discussion 的元数据将定期被发送到父页面(被嵌入的页面)。作为演示,尝试启用此选项并在此页面打开浏览器控制台。查看文档获取更多细节。
评论输入框会放在评论上方,这样用户可以在不滚动到讨论底部的情况下发表评论。
评论的加载将延迟到用户滚动到评论容器附近。 这是通过将 loading="lazy" 添加到 <iframe> 元素来完成的。
loading="lazy"
<iframe>
选择适合你网站的主题。找不到合适的?贡献一个新主题吧。
在你想让评论出现的位置添加以下 <script> 标签。但如果已经存在带有 giscus 类的元素,则评论会被放在那里。
<script>
giscus
<script src="https://giscus.app/client.js" data-repo="[在此输入仓库]" data-repo-id="[在此输入仓库 ID]" data-category="[在此输入分类名]" data-category-id="[在此输入分类 ID]" data-mapping="pathname" data-strict="0" data-reactions-enabled="1" data-emit-metadata="0" data-input-position="bottom" data-theme="preferred_color_scheme" data-lang="zh-CN" crossorigin="anonymous" async> </script>
你可以在嵌入的页面中使用 .giscus 和 .giscus-frame 选择器来自定义容器布局。
.giscus
.giscus-frame
如果你使用 giscus,请考虑在 GitHub 上 star 🌟 giscus 并为你的仓库添加 giscus 话题!🎉
你可以依照高级用法指南添加额外配置(例如允许特定来源)。
要在 React、Vue 和 Svelte 中使用 giscus,请查看 giscus 组件库。
如果你曾经使用过其它利用 GitHub Issue 的评论系统(如 utterances、gitalk),你可把已有的 issue 转换成 discussion。转换后,只要确保 discussion 标题与页面的映射关系正确,giscus 就会自动使用这些 discussion。
请查看 CONTRIBUTING.md。
giscus
由 GitHub Discussions 驱动的评论系统。让访客借助 GitHub 在你的网站上留下评论和反应吧!本项目受 utterances 强烈启发。
它如何运作
giscus 加载时,会使用 GitHub Discussions 搜索 API 根据选定的映射方式(如 URL、
pathname
、<title>
等)来查找与当前页面关联的 discussion。如果找不到匹配的 discussion,giscus bot 就会在第一次有人留下评论或回应时自动创建一个 discussion。要评论,访客必须按 GitHub OAuth 流程授权 giscus app 代表他发帖。或者访客也可以直接在 GitHub Discussion 里评论。你可以在 GitHub 上管理评论。
配置
语言
选择 giscus 的显示语言。找不到你的语言?贡献一个吧。
仓库
选择 giscus 连接到的仓库。请确保:
页面 ↔️ discussion 映射关系
选择页面与嵌入的 discussion 之间的映射关系。
当有多个具有相似标题的讨论时,避免由于 GitHub 的模糊搜索方法而导致的不匹配。查看文档获取更多细节。
Discussion 分类
选择新 discussions 所在的分类。 推荐使用公告(announcements)类型的分类,以确保新 discussion 只能由仓库维护者和 giscus 创建。
当搜索匹配的 discussion 时,giscus 将只搜索该分类。
特性
选择是否启用某些特性。
Discussion 的主帖子上的反应将会显示在评论前。
Discussion 的元数据将定期被发送到父页面(被嵌入的页面)。作为演示,尝试启用此选项并在此页面打开浏览器控制台。查看文档获取更多细节。
评论输入框会放在评论上方,这样用户可以在不滚动到讨论底部的情况下发表评论。
评论的加载将延迟到用户滚动到评论容器附近。 这是通过将
loading="lazy"
添加到<iframe>
元素来完成的。主题
选择适合你网站的主题。找不到合适的?贡献一个新主题吧。
启用 giscus
在你想让评论出现的位置添加以下
<script>
标签。但如果已经存在带有giscus
类的元素,则评论会被放在那里。你可以在嵌入的页面中使用
.giscus
和.giscus-frame
选择器来自定义容器布局。如果你使用 giscus,请考虑在 GitHub 上 star🌟 giscus 并为你的仓库添加 🎉
giscus
话题!高级用法
你可以依照高级用法指南添加额外配置(例如允许特定来源)。
要在 React、Vue 和 Svelte 中使用 giscus,请查看 giscus 组件库。
迁移
如果你曾经使用过其它利用 GitHub Issue 的评论系统(如 utterances、gitalk),你可把已有的 issue 转换成 discussion。转换后,只要确保 discussion 标题与页面的映射关系正确,giscus 就会自动使用这些 discussion。
正使用 giscus 的网站
贡献
请查看 CONTRIBUTING.md。
试一试👇 👇 👇