为 MKdocs 文档网站添加评论系统

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

MKdocs 集成 Giscus

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

• 安装 Giscus GitHub 应用，并授予将评论托管为 GitHub 讨论的仓库的访问权限。请注意，该仓库可以与您的文档不同。

  1. 访问 https://github.com/apps/giscus，点击 install 安装
  2. 选择用户，选择代码仓库，授予读写权限，点击安装
  3. 开启 discussions 功能，访问代码的 settings 在 Features 区域找到 discussions 勾选 discussions

• 获取代码片段，访问 Giscus，并通过其配置工具生成代码片段以加载评论系统。复制该代码片段以进行下一步。
  输入代码仓库名称，选择类别，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>

将 Giscus 嵌入页面

编辑 mkdocs.yml

theme:
  name: material
  custom_dir: overrides

创建以下目录结构

├─ overrides/
│  └─ partials/
│     └─ footer.html
└─ mkdocs.yml

将如下内容复制到 foot.html 文件中

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

重新启动 mkdocs 即可看到评论系统了

mkdocs serve

参考文档

为 MKdocs 博客网站添加评论系统

Adding a comment system

Adding a comment system