Adding a Comment Section to Docusaurus Blog Pages

How it Works

Docusaurus does not provide an out-of-the-box comment component, but we can customize components using the Swizzle feature.

The comment system used in this article is Giscus, which is an open-source comment system based on GitHub Discussions.

Creating Giscus Configuration

Repository Configuration

Go to your Docusaurus website’s repository page on GitHub, and ensure the repository is public.

If it’s not public, you can go to Settings - General, and at the very bottom under Danger Zone, select Change repository visibility.

After confirming the repository is public, check the Discussions box in the Features tab of Settings.

Go to the Giscus GitHub App page and follow the prompts to install it. Choose the Repository access scope according to your needs.

Getting the Repository API KEY

Open the Giscus official website and enter your repository address.

Select “Announcements” in the “Discussion Category”; the remaining options can be configured as needed. Once configured, you can get the configuration file at the bottom.

<script
  src="https://giscus.app/client.js"
  data-repo="your-name/your-repo"
  data-repo-id="your-repo-id"
  data-category="Announcements"
  data-category-id="your-category-id"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="preferred_color_scheme"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async
/>

Inserting the Giscus Component via Swizzle

First, install the Giscus React component in your project:

npm i @giscus/react

Create a file named GiscussComponents.js under /src/components/.

Copy the following code into it; the corresponding ID values can be found in the configuration file mentioned above:

// GiscussComponent.js
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="" // Enter your repo here
      repoId="" // Your repo id
      category=" " // Your category (default: Announcement)
      categoryId="" // Your category id
      mapping="pathname"
      term="Welcome to @giscus/react component!"
      strict="0"
      reactionsEnabled="1"
      emitMetadata="1"
      inputPosition="top"
      theme={colorMode}
      lang="zh-CN"
      loading="lazy"
      crossorigin="anonymous"
      async
    />
  );
}

Run Swizzle:

npm run swizzle

Select your theme configuration file (default is theme-classic):

> docusaurus swizzle

? Select a theme to swizzle: › - Use arrow-keys. Return to submit.
❯   @docusaurus/theme-classic
    @docusaurus/plugin-debug
    [Exit]

Scroll down to find BlogPostItem and press Enter to confirm:

BlogListPage (Unsafe)
    BlogListPaginator (Unsafe)
❯   BlogPostItem (Unsafe)
    BlogPostItem/Container (Unsafe)
    BlogPostItem/Content (Unsafe)

Press Enter to select Wrap and YES: I know what I am doing!:

? Which swizzle action do you want to do? › - Use arrow-keys. Return to submit.
❯   Wrap (Unsafe)
    Eject (Unsafe)
    [Exit]

Open /src/theme/BlogPostItem/index.js and modify the content to:

// src/theme/BlogPostItem/index.js
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 } = useBlogPost();
  const isBrowser = useIsBrowser();

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

  // Prevent ReferenceError: window is not defined (https://docusaurus.io/docs/advanced/ssg)
  var isCurrentUrlBlog = false;
  if (isBrowser) {
    isCurrentUrlBlog = window.location.pathname === "/blog";
  }

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

Next, add enableComments: true to the metadata at the top of the corresponding Blog page. For example:

---
title: A Title
authors: Author
tags: [Tags]
enableComments: true
---

Note: if you run swizzle again, the component will be restored to its original state and you will need to modify it again.