AstroのドキュメントテンプレートStarlightに、GitHub Discussionsを利用したコメント機能(Giscus)を導入したので備忘録を残します。
<h2 id="giscus%E3%81%A8%E3%81%AF" data-line="3" class="code-line"><a class="header-anchor-link" href="#giscus%E3%81%A8%E3%81%AF" aria-hidden="true"></a> Giscusとは</h2>
Giscusは、GitHub Discussionsを利用したコメントシステムです。
軽量で、GitHub認証を使用するため、スパム対策にも優れています。
<h2 id="%E5%89%8D%E6%8F%90%E6%9D%A1%E4%BB%B6" data-line="8" class="code-line"><a class="header-anchor-link" href="#%E5%89%8D%E6%8F%90%E6%9D%A1%E4%BB%B6" aria-hidden="true"></a> 前提条件</h2>
<ul data-line="10" class="code-line">
<li data-line="10" class="code-line">Astro Starlightのウェブサイトがセットアップされていること</li>
<li data-line="11" class="code-line">GitHubアカウントを持っていること</li>
<li data-line="12" class="code-line">GitHub Discussionsが有効になっているリポジトリがあること</li>
</ul>
<h2 id="%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E6%89%8B%E9%A0%86" data-line="14" class="code-line"><a class="header-anchor-link" href="#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E6%89%8B%E9%A0%86" aria-hidden="true"></a> インストール手順</h2>
<ol data-line="16" class="code-line">
<li data-line="16" class="code-line">starlight-giscusのインストール</li>
</ol>
まず、starlight-giscusプラグインをインストールします。ターミナルで以下のコマンドを実行してください。
pnpm:
<div class="code-block-container"><pre class="language-shell"><code class="language-shell code-line" data-line="21">pnpm add starlight-giscus
</code></pre></div>npm:
<div class="code-block-container"><pre class="language-shell"><code class="language-shell code-line" data-line="26">npm install starlight-giscus
</code></pre></div>yarn:
<div class="code-block-container"><pre class="language-shell"><code class="language-shell code-line" data-line="31">yarn add starlight-giscus
</code></pre></div><ol start="2" data-line="35" class="code-line">
<li data-line="35" class="code-line">Giscusアプリの設定</li>
</ol>
<a href="https://giscus.app/" target="_blank" rel="nofollow noopener noreferrer">Giscus公式サイト</a>で、あなたのリポジトリに対してGiscusを設定します。
必要な情報を入力し、スクリプトコードを生成してコピーしてください。
<ol start="3" data-line="41" class="code-line">
<li data-line="41" class="code-line">Astro設定ファイルの更新</li>
</ol>
<code>astro.config.mjs</code>ファイルを開き、以下のように設定を追加します。
<div class="code-block-container"><pre class="language-javascript"><code class="language-javascript code-line" data-line="45"># "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',
 }),
 ],
})
</code></pre></div><code>repo</code>、<code>repoId</code>、<code>category</code>、<code>categoryId</code>の値は、Giscusの設定で生成されたものに置き換えてください。
上記4つは必須項目ですが、他にもカスタマイズオプションがあります。詳細は後述します。
<h2 id="%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3" data-line="72" class="code-line"><a class="header-anchor-link" href="#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3" aria-hidden="true"></a> カスタマイズオプション</h2>
starlight-giscusプラグインには、以下のようなカスタマイズオプションがあります：
<ul data-line="76" class="code-line">
<li data-line="76" class="code-line"><code>mapping (string)</code>: ページとディスカッションのマッピング方法(ディスカッションのタイトルがどうなるか)</li>
<li data-line="77" class="code-line"><code>pathname (デフォルト)</code>: ページのパス名</li>
<li data-line="78" class="code-line"><code>URL</code>: ページのURL</li>
<li data-line="79" class="code-line"><code>&lt;title&gt;</code>: ページのタイトル</li>
<li data-line="80" class="code-line"><code>og:title</code>: ページのog:title</li>
<li data-line="81" class="code-line"><code>reactions (boolean)</code>: リアクション機能の有効/無効</li>
<li data-line="82" class="code-line"><code>inputPosition (string)</code>: 返信フォームの位置</li>
<li data-line="83" class="code-line"><code>bottom (デフォルト)</code>: コメントの下部</li>
<li data-line="84" class="code-line"><code>top</code>: コメントの上部</li>
<li data-line="85" class="code-line"><code>theme (string)</code>: コメント欄のテーマ</li>
<li data-line="86" class="code-line"><code>preferred_color_scheme (デフォルト)</code>: ユーザーのOSのテーマに合わせる</li>
<li data-line="87" class="code-line">その他は<a href="https://dragomano.github.io/starlight-giscus/configuration/#theme" target="_blank" rel="nofollow noopener noreferrer">Starlight-Giscusのドキュメント</a>を参照</li>
<li data-line="88" class="code-line"><code>lazy (boolean)</code>: 遅延ロードの有効/無効</li>
</ul>
これらのオプションを使用して、コメント機能をサイトに合わせてカスタマイズできます。
<h2 id="%E7%89%B9%E5%AE%9A%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%A7%E3%81%AE%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E7%84%A1%E5%8A%B9%E5%8C%96" data-line="92" class="code-line"><a class="header-anchor-link" href="#%E7%89%B9%E5%AE%9A%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%A7%E3%81%AE%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E7%84%A1%E5%8A%B9%E5%8C%96" aria-hidden="true"></a> 特定ページでのコメント無効化</h2>
そのままだと、下記のようなコメントを表示しなくても良いトップページなどでコメントが表示されてしまいます。
<img src="https://i.gyazo.com/96a2f69a5616ee742bcfa78bc7041417.png" alt="Image from Gyazo" />
コメントを表示したくないページがある場合は、frontmatterで制御できます。
<h3 id="%E8%A8%AD%E5%AE%9A%E6%89%8B%E9%A0%86" data-line="99" class="code-line"><a class="header-anchor-link" href="#%E8%A8%AD%E5%AE%9A%E6%89%8B%E9%A0%86" aria-hidden="true"></a> 設定手順</h3>
<ol data-line="101" class="code-line">
<li data-line="101" class="code-line"><code>src/content.config.ts</code>ファイルでスキーマを拡張します</li>
</ol>
<div class="code-block-container"><pre class="language-typescript"><code class="language-typescript code-line" data-line="103"># "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),
 }),
 }),
 }),
}
</code></pre></div><ol start="2" data-line="121" class="code-line">
<li data-line="121" class="code-line">コメントを無効にしたいページのfrontmatterに<code>giscus: false</code>を追加します。</li>
</ol>
<div class="code-block-container"><pre class="language-markdown"><code class="language-markdown code-line" data-line="123">---
title: コメント不要なページ
giscus: false
---
</code></pre></div><h2 id="starlight-blog%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6%E3%81%84%E3%82%8B%E5%A0%B4%E5%90%88" data-line="130" class="code-line"><a class="header-anchor-link" href="#starlight-blog%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6%E3%81%84%E3%82%8B%E5%A0%B4%E5%90%88" aria-hidden="true"></a> starlight-blogプラグインを使っている場合</h2>
starlight-blogプラグインを使っている場合は、<code>extend</code>の中で<code>blogSchema(context)</code>を呼び出して、その後に<code>giscus</code>を追加してください。
また、blogのページやtagのページでgiscusを無効にしたいのでデフォルトを<code>false</code>にします。
<h3 id="%E8%A8%AD%E5%AE%9A%E6%89%8B%E9%A0%86-1" data-line="135" class="code-line"><a class="header-anchor-link" href="#%E8%A8%AD%E5%AE%9A%E6%89%8B%E9%A0%86-1" aria-hidden="true"></a> 設定手順</h3>
<ol data-line="137" class="code-line">
<li data-line="137" class="code-line"><code>src/content.config.ts</code>ファイルでスキーマを拡張します</li>
</ol>
<div class="code-block-container"><pre class="language-typescript"><code class="language-typescript code-line" data-line="139"># "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) =&gt; blogSchema(context).extend({
 giscus: z.boolean().optional().default(false)
 })
 }),
 }),
}
</code></pre></div><ol start="2" data-line="158" class="code-line">
<li data-line="158" class="code-line">コメントを有効にしたいページのfrontmatterに<code>giscus: true</code>を追加します。</li>
</ol>
<div class="code-block-container"><pre class="language-markdown"><code class="language-markdown code-line" data-line="160">---
title: コメントを入れたいページ
date: 2025-03-17
giscus: true
---
</code></pre></div>

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