mkdocs-material集成评论系统

giscus¶

参考文章

安装¶

访问giscus，在你的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的内容¶

将上一步的代码段复制到下面的指定位置

{% 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" ? "dark" : "light"
      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" ? "dark" : "light"

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

使用自己的comments.html¶

在mkdocs-material中已经有了comments.html文件，我们需要使用我们自己定义的comments.html，以覆盖它。这其实是扩展主题的内容

使用评论¶

一个页面单独添加¶

在每个文档头前添加comments: true

---
comments: true
---

# Document title
...

所有页面¶

在mkdocs.yml的插件中添加

plugins:
  - comments