コンテンツにスキップ
Clameyes
Blog

Astro Starlightにコメント機能(Giscus)を導入する

AstroのドキュメントテンプレートStarlightに、GitHub Discussionsを利用したコメント機能(Giscus)を導入したので備忘録を残します。

Giscusとは

Giscusは、GitHub Discussionsを利用したコメントシステムです。

軽量で、GitHub認証を使用するため、スパム対策にも優れています。

前提条件

  • Astro Starlightのウェブサイトがセットアップされていること
  • GitHubアカウントを持っていること
  • GitHub Discussionsが有効になっているリポジトリがあること

インストール手順

  1. starlight-giscusのインストール

    まず、starlight-giscusプラグインをインストールします。ターミナルで以下のコマンドを実行してください。

    Terminal window
    pnpm add starlight-giscus

  2. Giscusアプリの設定

    Giscus公式サイトで、あなたのリポジトリに対してGiscusを設定します。

    必要な情報を入力し、スクリプトコードを生成してコピーしてください。

  3. Astro設定ファイルの更新

    astro.config.mjsファイルを開き、以下のように設定を追加します。

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightGiscus from 'starlight-giscus'
    

    export default defineConfig({
        integrations: [
            starlight({
                plugins: [
                    starlightGiscus({
                        repo: 'data-repo',
                        repoId: 'data-repo-id',
                        category: 'data-category',
                        categoryId: 'data-category-id'
                    })
                ],
                title: 'My Docs',
            }),
        ],
    })

    repo、repoId、category、categoryIdの値は、Giscusの設定で生成されたものに置き換えてください。

    上記4つは必須項目ですが、他にもカスタマイズオプションがあります。詳細は後述します。

カスタマイズオプション

starlight-giscusプラグインには、以下のようなカスタマイズオプションがあります：

  • mapping (string): ページとディスカッションのマッピング方法(ディスカッションのタイトルがどうなるか)
    • pathname (デフォルト): ページのパス名
    • URL: ページのURL
    • <title>: ページのタイトル
    • og:title: ページのog:title
  • reactions (boolean): リアクション機能の有効/無効
  • inputPosition (string): 返信フォームの位置
    • bottom (デフォルト): コメントの下部
    • top: コメントの上部
  • theme (string): コメント欄のテーマ
  • lazy (boolean): 遅延ロードの有効/無効

これらのオプションを使用して、コメント機能をサイトに合わせてカスタマイズできます。

特定ページでのコメント無効化

そのままだと、下記のようなコメントを表示しなくても良いトップページなどでコメントが表示されてしまいます。

Image from Gyazo

コメントを表示したくないページがある場合は、frontmatterで制御できます。

設定手順

  1. src/content.config.tsファイルでスキーマを拡張します

    src/content.config.ts
    import { defineCollection, z } from 'astro:content'
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    

    export const collections = {
        docs: defineCollection({
            loader: docsLoader(),
            schema: docsSchema({
                extend: z.object({
                    giscus: z.boolean().optional().default(true),
                }),
            }),
        }),
    }

  2. コメントを無効にしたいページのfrontmatterにgiscus: falseを追加します。

    ---
    title: コメント不要なページ
    giscus: false
    ---

starlight-blogプラグインを使っている場合

starlight-blogプラグインを使っている場合は、extendの中でblogSchema(context)を呼び出して、その後にgiscusを追加してください。

また、blogのページやtagのページでgiscusを無効にしたいのでデフォルトをfalseにします。

設定手順

  1. src/content.config.tsファイルでスキーマを拡張します

    src/content.config.ts
    import { defineCollection, z } from 'astro:content'
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    import { blogSchema } from 'starlight-blog/schema';
    

    export const collections = {
        docs: defineCollection({
            loader: docsLoader(),
            schema: docsSchema({
                extend: (context) => blogSchema(context).extend({
                    giscus: z.boolean().optional().default(false)
                })
            }),
        }),
    }

  2. コメントを有効にしたいページのfrontmatterにgiscus: trueを追加します。

    ---
    title: コメントを入れたいページ
    date: 2025-03-17
    giscus: true
    ---
タグ: