Adding a comment system

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 integration

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

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.

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:

<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>

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:

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

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

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.

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:

---
comments: true
---

# Document title
...

If you wish to enable comments for an entire folder, you can use the built-in meta plugin.

3.6 KiB Raw Blame History

Adding a comment system

Customization

Giscus integration

3.6 KiB

Raw Blame History