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 Giscus Configuration#
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 GiscusComponent.js under /src/components/.
Copy the following code into it; the corresponding ID values can be found in the configuration file mentioned above:
// GiscusComponent.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.
评论
登录后参与评论