giscus integration

[nicholaswilde]

🥅 Goal

I'm trying to enable giscus comments on my recipes site. I've add the comments to this page only for now as a test.

🤔 Problem

The giscus commenting system does not seem to show up at the bottom of the recipes page.

❓ Question

What else do I need to do to enable the giscus?

I've only enabled the overrides/partials/comments.html partial but it doesn't seem to take. Looking at the generated html page of coconut-curried-vegetables-with-ricedoesn't have giscus in it.

The only other examples I could find seemed to not use the comments.html partial like the instructions say to do.

👣 Steps performed

I've followed these instructions: Adding a comment system.

1. Installed the Giscus GitHub App
2. Enabled Discussions on nicholaswilde/recipes repo.
3. Generated snippet. Source:

 <script src="https://giscus.app/client.js"
    data-repo="nicholaswilde/recipes"
    data-repo-id="R_kgDOHIKkPg"
    data-category="Comments"
    data-category-id="DIC_kwDOHIKkPs4CRWOL"
    data-mapping="pathname"
    data-strict="0"
    data-reactions-enabled="1"
    data-emit-metadata="1"
    data-input-position="bottom"
    data-theme="light"
    data-lang="en"
    crossorigin="anonymous"
    async>
  </script>

4. Added comments: true front matter to the page. Source.

---
comments: true
---
# :coconut: Coconut Curried Vegetables with Rice
...

5. Created overrides/partials/comments.html override. Source.

{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  <!-- Insert generated code here -->
  <script src="https://giscus.app/client.js"
    data-repo="nicholaswilde/recipes"
    data-repo-id="R_kgDOHIKkPg"
    data-category="Comments"
    data-category-id="DIC_kwDOHIKkPs4CRWOL"
    data-mapping="pathname"
    data-strict="0"
    data-reactions-enabled="1"
    data-emit-metadata="1"
    data-input-position="bottom"
    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" ? "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 %}

6. Added overrides dir to mkdocs.yml. Source.

---
site_name: Recipes
site_description: A collection of my recipes.
site_author: Nicholas Wilde
site_url: https://nicholaswilde.io/recipes
copyright: Copyright © 2022 Nicholas Wilde
dev_addr: '0.0.0.0:8000'

repo_url: https://github.com/nicholaswilde/recipes
repo_name: nicholaswilde/recipes
edit_uri: "edit/main/docs/"

theme:
  name: material
  icon:
    repo: fontawesome/brands/github
    logo: fontawesome/solid/bowl-rice
+  custom_dir: overrides
...

📁 Directory structure

recipes
├─ overrides
│  └─ partials
│     └─ comments.html
└─ mkdocs.yml

[squidfunk]

Which version of Material for MkDocs are you using? The comments partial was introduced in 8.4.4. Make sure that you are at least on that version. Other than that your configuration looks good.

[nicholaswilde]

Which version of Material for MkDocs are you using? The comments partial was introduced in 8.4.4. Make sure that you are at least on that version.

I am using mhausenblas/mkdocs-deploy-gh-pages GH Action which looks like is using 8.4.1. That might be the issue. I will give an update once I have tested it.

Thanks 🙏🏽 for the quick reply.

[nicholaswilde]

Yep, that was it. I changed my GH Action to the suggested one in the docs and it worked.

[squidfunk]

Great! Using our recommended workflow makes sure you're always using the latest version.

[krahets]

Thanks! It seems mkdocs-material can not be upgraded by pip automatically, so I reinstalled it. Now giscus works well!