使用 GitHub Discussions 提供评论

Jekyll Obsidian 通过 Giscus 为已发布的文章关联 GitHub Discussion。站点本身仍是静态站点，不运行评论数据库或服务端 API，讨论数据保存在 GitHub 中。

访客可以直接在页面中阅读公开讨论。发表评论或表情回应时，需要通过 Giscus 使用 GitHub 身份验证。页面始终保留前往 GitHub Discussions 的普通链接，因此即使 JavaScript 被禁用或嵌入服务不可用，读者仍可在 GitHub 中继续讨论。

哪些页面会显示评论

所有内置主题都支持评论，但只有分类为 content_type: post 的页面可以挂载评论组件。普通页面、文档笔记、Blog 索引、标签及其他生成页面都不会显示评论。

要启用评论，必须先配置 website.comments。没有这个映射时，所有主题都会关闭评论。该映射存在但省略 enabled 时，由主题决定默认状态：

任何主题都可以通过 enabled: true 或 enabled: false 覆盖默认状态。

准备 Discussions 仓库

发布仓库和评论仓库可以是同一个公开仓库，也可以把社区讨论放在单独的公开仓库中。

1. 在评论仓库中打开 Settings → General → Features，启用 Discussions。具体步骤请参阅 GitHub 的仓库设置文档。
2. 创建一个分类，例如 Blog comments。建议使用 Announcement 格式，只有维护者和 Giscus 可以在该分类中创建讨论，访客仍可回复。
3. 为评论仓库安装 Giscus GitHub App。
4. 在 giscus.app 中填写仓库。在 页面 ↔️ discussion 映射关系 中选择 Discussion 的标题包含特定字符串，并勾选 使用严格的标题匹配。特定字符串可以留空，Jekyll Obsidian 会为每篇文章提供严格匹配的 website:post:... 标识。不要选择 pathname、URL、页面标题、og:title 或特定 discussion 号。
5. 选择分类，然后复制生成的仓库 ID 与分类 ID。不要根据显示名称猜测这些 ID，也不要复制生成的 <script> 标签；映射方式、标识和运行时选项都由 Jekyll Obsidian 管理。

评论仓库必须公开，否则访客无法读取讨论。这些属于运行时前置条件，不是构建前置条件。构建过程不会启用 Discussions、创建分类、安装 GitHub App、检查其远程状态，也不会连接 GitHub。尚未满足或之后被关闭的远程条件都不会让静态构建失败。

配置站点

在 .github/jekyll-obsidian.yml 中，把评论配置放在受管的 source 和 theme 行之外：

website:
  # jekyll-obsidian:managed-start
  source: docs
  theme: minimal
  # jekyll-obsidian:managed-end
  repository: owner/site
  comments:
    enabled: true
    # 可选。省略后复用 website.repository。
    repository: owner/community
    repository_id: R_kgDOxxxxxxxx
    category: Blog comments
    category_id: DIC_kwDOxxxxxxxx

只有当 website.repository 已经指向评论仓库时，才可以省略 repository。启用评论时必须能取得格式正确的仓库标识。

Giscus 需要 repository_id、category 和 category_id 才能载入，但构建不要求这些值全部就绪。缺少任意一项时，编译器会产生 comments_unconfigured 警告。符合条件的文章会显示不可交互的待配置提示和评论仓库链接，但不会载入 Giscus 客户端。你可以先启用评论，等 Discussions 与 Giscus App 准备完成后再补充这些值。

未知配置项、非布尔值的 enabled、格式错误的仓库名，以及非字符串的服务配置值仍属于致命配置错误。

website/bin/integrate 会保留已有的评论配置，但不会主动创建它。修改宿主配置后，请运行一次生产构建：

JEKYLL_ENV=production website/bin/build \
  --url https://docs.example.com \
  --baseurl "" \
  --destination _site

控制单篇文章

站点级评论启用后，每篇已发布文章都会显示评论。可以用 YAML 布尔值关闭其中一篇：

---
publish: true
content_type: post
date: 2026-08-04
comments: false
---

如果 website.comments 缺失或已关闭，页面属性无法单独开启评论。comments: true 也不会把普通页面或文档笔记改成文章；请使用 content_type: post，或把文件放入配置的文章目录。

讨论串标识与创建时机

每篇文章都使用由逻辑笔记路径生成的严格标识：

website:post:blog/my-post

修改站点域名、baseurl 或 permalink 不会更换 Discussion。移动或重命名源笔记会改变标识，从而使用新的讨论串。已有 Discussion 不会自动迁移。

同一逻辑文章的不同语言版本共享一个 Discussion。Giscus 支持当前页面语言时，组件会使用该语言；否则回退到英文。

构建和首次打开页面都不会创建空 Discussion。访客第一次提交评论或表情回应时，Giscus 才会创建讨论。因此，尚无 Discussion 是正常且可用的状态。

运行时与降级行为

本地开发环境不会连接 Giscus，只显示“评论仅在发布站点中载入”的提示，以及指向 Discussions 页面的链接。

只有服务配置完整时，生产和 CI 构建才会在符合条件的文章中载入 Giscus 客户端。iframe 会在评论区域接近视口时延迟载入，自动匹配站点的浅色或深色配色，并在配色切换后同步更新。

如果 Discussions 未启用、Giscus App 未安装或外部客户端不可用，站点本身仍会正常运行。评论区域会进入非致命的暂不可用状态，并保留服务器渲染的 GitHub 链接。这些运行时问题不会影响页面的其他功能或之后的构建。

启用评论的页面会获得范围受限的内容安全策略，允许 Giscus 脚本、iframe 和默认样式表。其他页面继续使用仅允许站点自身资源的策略。

隐私与来源限制

评论和表情回应是评论仓库中的公开 GitHub 数据。访客发表评论前需要使用 GitHub 身份验证，维护者也需要在 GitHub Discussions 中进行审核和管理。如果站点有额外的隐私或合规要求，请先评估 GitHub 与 Giscus 的相关政策。

若要阻止其他站点嵌入你仓库中的 Discussions，请在评论仓库根目录添加 giscus.json：

{
  "origins": ["https://docs.example.com"]
}

originsRegex 等仓库级配置请参阅 Giscus 高级用法。

排查问题