Docusaurus のブログページにコメント欄を追加する

仕組み

Docusaurus の公式では、そのまま使えるコメントセクション用コンポーネントは提供されていませんが、Swizzle 機能を利用することでコンポーネントをカスタマイズして実装できます。

本文で使用するコメントシステムは Giscus です。これは GitHub Discussions をベースにしたオープンソースのコメントシステムです。

Giscus の設定を作成する

リポジトリの設定

GitHub で Docusaurus サイトのリポジトリページに移動し、リポジトリが公開（Public）に設定されていることを確認してください。

公開されていない場合は、Settings - General の一番下にある Danger Zone - Change repository visibility から変更できます。

リポジトリが公開状態であることを確認したら、Settings の Features タブ内にある Discussions にチェックを入れます。

Giscus GitHub App ページに移動し、案内に従ってインストールします。必要に応じて Repository access の範囲を選択してください。

リポジトリの API KEY を取得する

Giscus 公式サイトを開き、自分のリポジトリのアドレスを入力します。

「Discussion カテゴリ」で「📣 Announcements」を選択します。その他のオプションは必要に応じて設定してください。設定が完了すると、ページ下部に設定ファイルの内容が表示されます。

<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
/>

Swizzle を使って Giscus コンポーネントを挿入する

まず、プロジェクトに Giscus React コンポーネントをインストールします。

npm i @giscus/react

/src/components/ 配下に GiscussComponents.js ファイルを作成します。

以下のコードをコピーして貼り付けます。各 ID の値は先ほど取得した設定ファイルから探してください。

// 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="" //这里填写你的repo
      repoId="" //你的repo id
      category=" " //你的category（默认 Announcement）
      categoryId="" //你的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
    />
  );
}

Swizzle を実行します。

npm run swizzle

使用しているテーマ設定を選択します（デフォルトは theme-classic）。

> docusaurus swizzle

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

下にスクロールして BlogPostItem を探し、Enter キーで確定します。

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

Enter キーで Wrap と 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]

/src/theme/BlogPostItem/index.js を開き、内容を以下のように修正します。

// 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;

  // 防止 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 />}
    </>
  );
}

次に、対象となるブログ記事の冒頭（Front Matter）に enableComments: true を追加します。例：

---
title: 一个标题
authors: 作者
tags: [标签]
enableComments: true
---

swizzle を再実行するとコンポーネントが元に戻ってしまうため、再度修正が必要になることに注意してください。