跳转至

MaterialX 接入 Giscus 评论系统

Giscus 是一个基于 GitHub Discussions 的轻量级评论系统。它让你可以在静态网站(如博客、文档站)中嵌入评论区,而所有评论数据实际上都存储在你指定的 GitHub 仓库的讨论区里。

这里记录一下个人的 MkDocs(基于 MaterialX 主题)站点,在集成 giscus 评论的同时,并让它使用 data-mapping="number" 精确与指定的 Discussion 一一匹配对应。核心思路是:覆盖主题的 comments.html 模板,在页面 front matter 中为每篇文章手动指定一个 GitHub Discussion 编号,然后让 giscus 脚本动态读取这个编号作为 data-term。

1. 获取 Discussion 编号

Giscus 的 number 映射模式依赖一个明确的数字 ID。你需要先在 GitHub 仓库的 Discussions 中为你的文档页面创建(或找到)对应的讨论帖,并记下其编号。

编号就是讨论帖 URL 末尾的数字。例如 https://github.com/owner/repo/discussions/42,编号就是 42。

2. 配置 MkDocs 主题覆盖

在 mkdocs.yml 中确保启用了 custom_dir:

theme:
  name: material
  custom_dir: overrides

然后在 overrides/partials/comments.html 文件中编写逻辑。由于 MaterialX 使用 Jinja2 模板,你可以根据页面元数据(front matter)来条件化地输出 giscus 脚本。

3. 编写 comments.html 模板

仅当页面 front matter 中存在 discussion_number 时才渲染 giscus 评论区(使用 number 映射),否则什么都不输出。关键点:data-term 的值必须动态填入 {{ page.meta.discussion_number }},这是 number 映射生效的必要条件。

{% if page.meta and page.meta.discussion_number %}
  <h2 id="__comments">评论</h2>
  <script src="https://giscus.app/client.js"
          data-repo="你的用户名/你的仓库名"
          data-repo-id="你的仓库ID"
          data-mapping="number"
          data-term="{{ page.meta.discussion_number }}"
          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>
  <!-- Synchronize Giscus theme with palette -->
  <script>
    var giscus = document.querySelector("script[src*=giscus]")

    // Set palette on initial load
    var palette = __md_get("__palette")
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate"
        ? "transparent_dark"
        : "light"

      // Instruct Giscus to set theme
      giscus.setAttribute("data-theme", theme) 
    }

    // Register event handlers after documented loaded
    document.addEventListener("DOMContentLoaded", function() {
      var ref = document.querySelector("[data-md-component=palette]")
      ref.addEventListener("change", function() {
        var palette = __md_get("__palette")
        if (palette && typeof palette.color === "object") {
          var theme = palette.color.scheme === "slate"
            ? "transparent_dark"
            : "light"

          // Instruct Giscus to change theme
          var frame = document.querySelector(".giscus-frame")
          frame.contentWindow.postMessage(
            { giscus: { setConfig: { theme } } },
            "https://giscus.app"
          )
        }
      })
    })
  </script>
{% endif %}

或者可以考虑,如果页面 front matter 中有 discussion_number,则使用 number 映射;否则可以回退到 pathname 或直接不显示,按需修改就行,不会写也可以直接问 AI。

4. 在 Markdown 页面中指定编号

在你的 Markdown 文件(如 docs/index.md)的 front matter 中,添加你之前记下的讨论编号:

---
title: 我的文档页面
comments: true
discussion_number: 42
---

最后,重新构建站点。

欢迎留言评论