Docusaurus 블로그에 댓글 기능 추가하기 - giscus

Docusaurus 블로그 커스터마이징 첫 번째 포스트입니다. 이번 글에서는 giscus를 이용해 Docusaurus 블로그에 댓글 기능을 추가하는 방법을 알아보겠습니다.

Giscus란

Giscus는 GitHub의 Discussions 기능을 활용하여 댓글을 남기고 관리할 수 있는 오픈소스 댓글 시스템으로, 아래와 같은 특징이 있습니다.

• GitHub 계정 기반: 댓글을 남기려면 GitHub 계정이 필요하며, 이는 스팸을 줄이는 효과가 있습니다.
• GitHub Discussions 활용: 블로그 포스트마다 자동으로 Discussion 스레드가 생성되며, 댓글이 Discussions에 저장됩니다.
• 완전 무료: GitHub에서 제공하는 기능을 활용하기 때문에 추가적인 비용이 들지 않습니다.
• Markdown 지원: GitHub Discussions와 동일하게 Markdown을 사용하여 댓글을 작성할 수 있습니다.
• 반응(Reaction) 기능 제공: 단순한 댓글뿐만 아니라, 이모지 반응(👍, 👎 등)도 가능합니다.
• 다크 모드 지원: 웹사이트의 테마에 맞춰 자동으로 다크 모드를 적용할 수 있습니다.

이제 Docusaurus 블로그에 Giscus를 적용하는 방법을 살펴보겠습니다.

Docusaurus에 Giscus 적용하기

1. GitHub Discussion 활성화

Giscus를 사용하려면 댓글을 저장할 공간이 필요합니다. GitHub Discussions 기능을 활성화하면, 블로그 포스트마다 자동으로 Discussion 스레드가 생성되어 댓글이 저장됩니다. 이를 위해 GitHub Pages로 사용하고 있는 [username].github.io 레포지토리로 이동한 뒤, Settings - General에서 Features의 Discussions를 체크해 줍니다.

설정 후, 레포지토리 상단에 Discussions 탭이 생성된 것을 확인할 수 있습니다.

2. Giscus 앱 설치

Giscus가 GitHub Discussions을 활용할 수 있도록 GitHub에 giscus 앱을 설치해 줍니다. 설치 링크로 들어가서 Install 버튼을 클릭한 후, [username].github.io 레포지토리에 giscus 앱을 설치합니다.

3. Giscus Configuration 생성

이제 giscus에 접속하여 아래와 같은 정보를 입력합니다.

• 사용할 언어
• Giscus와 연결할 레포지토리
• 블로그 페이지와 Discussion을 연결하는 방식
• 새로운 Discussion이 생성될 카테고리
• 기능, 테마

입력 후, 아래와 같이 자동으로 생성된 script 태그 코드를 복사해 둡니다. 이 코드는 다음 단계에서 필요하니 잘 메모해 두시기 바랍니다.

<script src="https://giscus.app/client.js"
    data-repo="[ENTER REPO HERE]"
    data-repo-id="[ENTER REPO ID HERE]"
    data-category="[ENTER CATEGORY NAME HERE]"
    data-category-id="[ENTER CATEGORY ID HERE]"
    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="ko"
    crossorigin="anonymous"
    async>
</script>

4. Docusaurus에 Comments Component 추가

Docusaurus 프로젝트 폴더에서 @giscus/react 패키지를 설치해 줍니다.

npm install @giscus/react

다음으로 src/components 디렉토리에 Comments 폴더를 만들고, index.tsx 파일을 생성하여 아래와 같이 작성해 줍니다. 이때 앞서 메모해 둔 Giscus Configuration을 이용하여 값을 채워주시면 됩니다.

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

export default function Comments(): JSX.Element {
  const { colorMode } = useColorMode();

  return (
    <div>
      <Giscus
        id="comments"
        repo="[ENTER REPO HERE]"
        repoId="[ENTER REPO ID HERE]"
        category="[ENTER CATEGORY NAME HERE]"
        categoryId="[ENTER CATEGORY ID HERE]"
        mapping="pathname"
        strict="1"
        reactionsEnabled="1"
        emitMetadata="0"
        inputPosition="bottom"
        theme={colorMode === "dark" ? "dark_tritanopia" : "light_tritanopia"}
        lang="ko"
        loading="lazy"
      />
    </div>
  );
}

5. Blog 포스트에 Comments 추가

이제 Swizzling을 이용해 블로그 글 하단에 댓글이 표시되도록 Docusaurus의 블로그 레이아웃을 수정해 줄 겁니다.

우선, 프로젝트 폴더에서 아래 명령을 입력하면 src/theme 디렉토리에 BlogPostItem/index.tsx가 생성됩니다.

npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap --typescript

노트

위 명령어 실행 시 나타나는 warning은 "YES: I know what I am doing!"를 선택해 주시면 됩니다.

생성된 index.tsx 파일을 아래와 같이 수정해 줍니다.

import React, {type ReactNode} from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import type BlogPostItemType from '@theme/BlogPostItem';
import type {WrapperProps} from '@docusaurus/types';
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import Comments from "@site/src/components/Comments";

type Props = WrapperProps<typeof BlogPostItemType>;

export default function BlogPostItemWrapper(props: Props): ReactNode {
  const { metadata, isBlogPostPage } = useBlogPost();
  const { comments = true } = metadata.frontMatter;

  return (
    <>
      <BlogPostItem {...props} />
      {comments && isBlogPostPage && <Comments />}
    </>
  );
}

이제 블로그 포스트 글을 확인해 보면 아래와 같이 Comments가 생긴 것을 확인할 수 있습니다.

참고 사이트

• Add Giscus Comments to Docusaurus 3 Blog Posts and Doc Pages: https://rikublock.dev/docs/tutorials/giscus-integration/