How to add Giscus comments to Docusaurus

Goal

This post is a step-by-step description of how to add Giscus, a commenting system powered by GitHub Discussions, to a static website generated by Docusaurus.

Setup Giscus

Follow the steps in the sections of the current chapter to set up Giscus and connect it to the GitHub discussions.

Enable GitHub discussion

• Create Github repository in your Github account where comments are stored in Discussion section.
• In the main page of created repository go to Settings.
• Under "Features" section, click "Set up discussions".
• Edit the template in "Start a new discussion" and click "Start discussion".

Enable Giscus

• Configure giscus in your GitHub account.
• In Section "Repository access" add only created repository from previous step to be accessed by giscus and click "Save".

Get repository API key

• Login with GitHub account in GraphQL API Explorer.
• Use following query to fetch the id of created repository, discussion categories with its details (e.g. id and name). Note! Replace owner and name with your GitHub account name and name of repository you created.

query { 
  repository(owner: "nameOfYourGitHubAccount", name:"nameOfCreatedRepository"){
    id
    discussionCategories(first:10) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

The result json object will be similar to:

{
  "data": {
    "repository": {
      "id": "R_kgDOIVqhTg",
      "discussionCategories": {
        "edges": [
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSES",
              "name": "Announcements"
            }
          },
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSET",
              "name": "General"
            }
          },
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSEV",
              "name": "Ideas"
            }
          },
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSEX",
              "name": "Polls"
            }
          },
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSEU",
              "name": "Q&A"
            }
          },
          {
            "node": {
              "id": "DIC_kwDOIVqhTs4CSSEW",
              "name": "Show and tell"
            }
          }
        ]
      }
    }
  }
}

Create Giscus component

• Install @giscus/react package

npm i @giscus/react

• Create Giscus Component, e.g. under /src/components/GiscusComponent as follows:

import React from 'react';
import Giscus from "@giscus/react";
import { useColorMode } from '@docusaurus/theme-common';

export default function GiscusComponent() {
  const { colorMode } = useColorMode();

  return (
    <Giscus    
      repo="nameOfYourGitHubAccount/nameOfCreatedRepository"
      repoId="idOfCreatedRepo"
      category="General"
      categoryId="IdOfDiscussionCategory"  // E.g. id of "General"
      mapping="url"                        // Important! To map comments to URL
      term="Welcome to @giscus/react component!"
      strict="0"
      reactionsEnabled="1"
      emitMetadata="1"
      inputPosition="top"
      theme={colorMode}
      lang="en"
      loading="lazy"
      crossorigin="anonymous"
      async
    />
  );
}

Create BlogPostItem component

• Create BlogPostItem component to wrap blog posts with Giscus commenting system as follows:

npm run swizzle [theme name] [component name] -- --wrap

# Example:
npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap

This will create a BlogPostItem component under src/theme. Edit index.js as follows:

import React from 'react';
import { useBlogPost } from '@docusaurus/theme-common/internal'
import BlogPostItem from '@theme-original/BlogPostItem';
import GiscusComponent from '@site/src/components/GiscusComponent';
import useIsBrowser from '@docusaurus/useIsBrowser';

export default function BlogPostItemWrapper(props) {
  const { metadata, isBlogPostPage } = useBlogPost()
  const isBrowser = useIsBrowser();

  const { frontMatter, slug, title } = metadata
  const { enableComments } = frontMatter

  return (
    <>
      <BlogPostItem {...props} />
      {(enableComments && isBlogPostPage) && (
        <GiscusComponent />
      )}
    </>
  );
}

Note that the useBlogPost() Hook is used in BlogPostItem component to make activation of comments per blog post configurable. The key value enableComments: true must be added to your blog post md file in order to activate commenting for it. E.g.:

---
title: Title of blog post
authors: author
tags: [keywordOne, keywordTwo]
enableComments: true # for Gisqus
---

I have enabled the comment function in the current post, which can be used as a demo. Feel free to hit the "Like" button if you found this post helpful, or post your question in the comment if you have one.

References

giscus.app
graphql.org
Add comment system to your static site with Giscus