添加评论系统¶

¥Adding a comment system¶

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

¥Material for MkDocs allows to easily add the third-party comment system of your choice to the footer of any page by using theme extension. As an example, we'll be integrating Giscus, which is Open Source, free, and uses GitHub discussions as a backend.

定制¶

¥Customization¶

Giscus 集成¶

¥Giscus integration¶

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

¥Before you can use Giscus, you need to complete the following steps:

安装 Giscus GitHub App ，并授予将评论托管为 GitHub 讨论的仓库的访问权限。请注意，该仓库可以与您的文档不同。
¥Install the Giscus GitHub App and grant access to the repository that should host comments as GitHub discussions. Note that this can be a repository different from your documentation.
访问 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>
```
```
<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>
```
<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> <script src="https://giscus.app/client.js" data-repo="<用户名>/<存储库> " data-repo-id="... " data-category="..." data-category-id="..." data-mapping="路径名" data-reactions-enabled="1" data-emit-metadata="1" data-theme="light" data-lang="en" crossorigin="anonymous" async > </script>

comments.html部分（默认为空）是添加Giscus生成的代码片段的最佳位置。请按照主题扩展指南，使用以下命令覆盖 comments.html 部分：

¥Visit Giscus and generate the snippet through their configuration tool to load the comment system. Copy the snippet for the next step. The resulting snippet should look similar to this:

{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <!-- Insert generated snippet here -->

  <!-- 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) // (1)!
    }

    // 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 %}

此代码块确保当调色板设置为slate时， Giscus会以暗色主题进行渲染。请注意，有多个暗色主题可供选择，因此您可以根据自己的喜好进行更改。
¥This code block ensures that Giscus renders with a dark theme when the palette is set to slate. Note that multiple dark themes are available, so you can change it to your liking.

将突出显示的行替换为您在上一步中使用Giscus配置工具生成的代码片段。如果您从上面复制了该代码片段，则可以通过将comments front matter 属性设置为true来在页面上启用评论：

¥The comments.html partial (empty by default) is the best place to add the snippet generated by Giscus. Follow the guide on theme extension and override the comments.html partial with:

---
comments: true
---

# Page title
...

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

¥Replace the highlighted line with the snippet you generated with the Giscus configuration tool in the previous step. If you copied the snippet from above, you can enable comments on a page by setting the comments front matter property to true: