Option to enable comments based on either github issues (utterances) or discussions (giscus)

[sbamin]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

I have enabled giscus based commenting as per https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/?h=giscus#giscus-integration Given giscuss is based on github discussions (beta), I prefer to use more stable, github issues api for my website commenting framework. I can enable commenting using https://utteranc.es/ using following code in content block after {{ super() }} in overrides/main.html file. While this works without an issue for a default theme (light in my case), toggling to alternate (dark) theme does not handle theme change for comment frame. I suspect an issue with document.addEventListener in my code and wish it can be fixed.

Thanks!

  {% if config.extra.comments.enabled and page and page.meta and page.meta.comments == false %}
  	<!-- disbale comments -->
  {% else %}
	<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
	{% if config.extra.comments.mode == "giscus" %}
		<script src="https://giscus.app/client.js"
		        data-repo="<user/repo>"
		        data-repo-id="<data-repo_id=>"
		        data-category="Announcements"
		        data-category-id="<category_id>"
		        data-mapping="pathname"
		        data-reactions-enabled="1"
		        data-emit-metadata="0"
		        data-input-position="top"
		        data-theme="light"
		        data-lang="en"
		        crossorigin="anonymous"
		        async>
		</script>
	{% else %}
		<script src="https://utteranc.es/client.js"
		        repo="<user/repo>"
		        issue-term="title"
		        label="<label>"
		        theme="github-light"
		        crossorigin="anonymous"
		        async>
		</script>
	{% endif %}

	<!-- Reload on palette change -->
	<script>
	var palette = __md_get("__palette")
	if (palette && typeof palette.color === "object")
	  if (palette.color.scheme === "slate") {
	  	{% if config.extra.comments.mode == "giscus" %}
	    	var giscus = document.querySelector("script[src*=giscus]")
	    	giscus.setAttribute("data-theme", "dark")
	    {% else %}
	    	var utterances = document.querySelector("script[src*=utteranc]")
	    	utterances.setAttribute("theme", "github-dark")
	    {% endif %}
	  }

	/* 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"
	    {% if config.extra.comments.mode == "giscus" %}
	      /* Instruct Giscus to change theme */
	      var frame = document.querySelector(".giscus-frame")
	      frame.contentWindow.postMessage(
	        { giscus: { setConfig: { theme } } },
	        "https://giscus.app"
	      )
	    {% else %}
	      /* Instruct Utterances to change theme */
	      var frame = document.querySelector(".utterances-frame")
	      frame.contentWindow.postMessage(
	        { utterances: { setConfig: { theme } } },
	        "https://utteranc.es"
	      )
	    {% endif %}
	    }
	  })
	})
	</script>
  {% endif %}

and my mkdocs.yml contains following under extra config:

extra:
  comments:
    enabled: true
    # defaults to utterances unless replaced with mode: giscus
    mode: utterances
    type: issues

Use Cases

Let users select either github issue or discussion based commenting system. Given github issues api is stable than github discussions and giscus app (beta), enabling issue-based commenting may be less prone to breaking changes.

Screenshots / Mockups

not applicable

[squidfunk]

Thanks for suggesting. Comment systems are integrated through customization, so there's nothing to be done on our end. You can use custom front matter to customize the appearance or put configuration under the extra key in mkdocs.yml as you already did.

Converting to discussion.

[sbamin]

Thanks! I am not familiar with java scripts and hoping that either you or someone here can review my customization to fix an issue under Reload on palette change. Unlike giscus, I cannot see automatic change in theme for utterances when I toggle mkdocs material theme from light to dark or vice versa.

[squidfunk]

Maybe somebody else can help. Otherwise, you may probably have more luck asking this on the utterances discussion board.

[sbamin]

Done! Thanks for the tip on checking with utterances where someone already had a similar issue. I needed to change variable, theme and message body to let utterances toggle theme based on site theme.

Here is a working code: https://github.com/sbamin/code101/blob/778d0aa4b8522f45e0821241f4ced70759c7205d/web/overrides/main.html#L120
and a webpage, https://code.sbamin.com/hpc/#acknowledgments