Skip to content

Comment System

Comment system is support by giscus. The majority of the configuration follows the official guide. But there are some changes.

Giscus configuration

Recommended configuration:

  • Page Mapping: pathname

    💡 The page URL is bind to relative path to the page code. Thus don't change the file name if there have been comments already.

  • Strict title matching: enabled

  • Discussion Category:

    1. Create a new category named Comments with the format Announcements

      💡 A new category avoids messing up normal discussions and the format Announcements ensures that new discussions can only be created by maintainers and giscus.

    2. Select this Comments

  • Features:

    • ✅ Enable reactions for the main post
    • ✅ Place the comment box above the comments
    • ✅ Load the comments lazily

Now the snippet should look similar to this

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

Finally, enable giscus in mkdocs.yml:

mkdocs.yml
giscus: true

Customize comments.html partial

Follow the official guide but edit the comments.html from

official snippet
{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  ...
{% endif %}

to

revision
{% if config.giscus and not (page and page.meta and page.meta.disable_comments) %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
  ...
{% endif %}

The revision enables comment system for all pages without use of paid plugin meta. To disable the feature for certain page, add the following meta to the head of the markdown code.

---
disable_comments: true
---

Comments