Skip to content

Adding a Free Comment System Powered by GitHub Issues

Giscus is a comment module powered by GitHub's Discussion system. Users can log in via their GitHub account, and it supports Markdown-formatted comments. The interface is both clean and attractive.

See the bottom of this page for an example.

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

Configure a Dedicated Repository for Giscus

  • The repository must be public, otherwise visitors will not be able to view the discussions.
  • The giscus app must be installed, otherwise visitors will not be able to comment or respond. Click here to install.
  • The Discussions feature must be enabled in your repository. The path to enable it is Settings - Features - Discussions of the project.

Generate Your Own Configuration Online

Visit Giscus and use their configuration tool to generate the code snippet to load the comment system. Copy that code snippet for the next step. The generated 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>

Configure comments.html and Place It Under the overrides/partials Directory

comments.html (empty by default) is the best place to add the code snippet generated by Giscus. Follow the theme extension guide and override comments.html. Replace the highlighted lines with the code snippet generated by the Giscus configuration tool in the previous step. 

{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <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 %}
File structure: 
.
├─ overrides/
│  └─ partials
│     └─ comments.html
│  └─ base.html
└─ mkdocs.yml

Done

Now you can enable comments on a page by setting comments to true in the md file:

---
comments: true
---

# Page title
...

Official documentation: 1. https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/?h=comment

Comments

本文总阅读量次