添加评论系统

MkDocs 的 Material 主题可以轻松地将您选择的第三方评论系统添加到任何页面的页脚，方法是使用主题扩展。作为示例，我们将集成 Giscus，这是一个开源的、免费的，并使用 GitHub 讨论作为后端的系统。

自定义

Giscus 集成

在你可以使用 Giscus 之前，你需要完成以下步骤：

安装 Giscus GitHub App 并授予访问应该托管评论作为 GitHub 讨论的仓库的权限。注意，这可以是与你的文档不同的仓库。
访问 Giscus 并通过他们的配置工具生成代码片段 以加载评论系统。复制下一步需要的代码片段。生成的代码片段应该看起来像这样：

<script
  src="https://giscus.app/client.js"
  data-repo="<username>/<repository>"
  data-repo-id="..."
  data-category="..."
  data-category-id="..."
  data-mapping="pathname"
  data-reactions-enabled="1"
  data-emit-metadata="1"
  data-theme="light"
  data-lang="en"
  crossorigin="anonymous"
  async
></script>

comments.html 部分（默认为空）是添加由 Giscus 生成的代码片段的最佳位置。按照主题扩展和 [覆盖 comments.html 部分][overriding partials] 的指南进行操作：

{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- 在此处插入生成的代码片段 -->

<!-- 使 Giscus 主题与调色板同步 -->
<script>
  var giscus = document.querySelector("script[src*=giscus]");

  /* 在初始加载时设置调色板 */
  var palette = __md_get("__palette");
  if (palette && typeof palette.color === "object") {
    var theme = palette.color.scheme === "slate" ? "dark" : "light";
    giscus.setAttribute("data-theme", theme); // (1)!
  }

  /* 在文档加载后注册事件处理程序 */
  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" ? "dark" : "light";

        /* 指示 Giscus 更改主题 */
        var frame = document.querySelector(".giscus-frame");
        frame.contentWindow.postMessage(
          { giscus: { setConfig: { theme } } },
          "https://giscus.app"
        );
      }
    });
  });
</script>
{% endif %}

该代码块确保当调色板设置为 slate 时，Giscus 以暗色主题呈现。请注意，有多个暗色主题可供选择，因此你可以根据喜好进行更改。

将高亮的行替换为你在上一步使用 Giscus 配置工具生成的代码片段。如果你从上面复制了代码片段，你可以通过将 comments 前端 matter 属性设置为 true 来启用页面上的评论：

---
comments: true
---
# 文档标题

如果你希望为整个文件夹启用评论，你可以使用内置的元插件。