@giscusgiscus

giscus

GitHub Discussionsを利用したコメントシステムです。サイト訪問者にGitHubを利用したコメント・リアクション機能を提供しましょう！このプロジェクトはutterancesから着想を得ています。

注記
giscusは現在も活発に開発が行われています。GitHubも同様にDiscussionsとそのAPIの開発を活発に行っています。そのため、giscusの機能の一部が正常に動作しなくなったり、変更されたりする場合があります。

仕組み

giscus読み込み時にGitHub Discussions search APIを利用してページ連携設定(URL、パス、<title>など)に基づき紐づけられたDiscussionを読み込みます。もし紐づけられたDiscussionがない場合、giscusは最初にコメントやリアクションが為された際に自動的にDiscussionを作成します。

サイト訪問者のコメントはgiscus appによって訪問者に代わって投稿されるために、GitHub OAuth flowを利用した連携設定が行われる必要があります。あるいは、サイト訪問者はGitHub Discussionに直接コメントすることも可能です。コメントはGitHub上で管理することができます。

設定

言語

giscusの利用する言語を指定してください。 お使いの言語が見つからない場合は、翻訳データを送信してみてください。

リポジトリ

giscusが利用するリポジトリを指定してください。 次のことを確認してください:

  1. リポジトリが公開状態である。訪問者が閲覧できる必要があります。
  2. giscusアプリがインストールされている。訪問者がコメントやリアクションを追加するのに必要です。
  3. Discussions機能を有効化するに従ってDiscussions機能が有効化されている

Discussionsが連携されるGitHubのリポジトリが公開状態である。

ページとDiscussions連携設定

ページとコメントの連携方法を指定してください

giscusはページのpathnameを含むページを検索します。

giscusはページのURLを含むページを検索します。

giscusはページの<title>タグの値を含むページを検索します。

giscusはページの<meta property="og:title">タグの値を含むページを検索します。

giscusは特定の条件文を含むページを検索します。

giscusはDiscussionを指定された番号から読み込みます。この方法では自動でDiscussionが生成されません。

類似したタイトルのディスカッションが複数ある場合は、GitHubのあいまい検索方法による不一致を回避します。詳細はドキュメントをご参照ください。

Discussionで使用するカテゴリ

新しいDiscussionsの作成時に使用するカテゴリを指定してください。 新しいDiscussionsの作成を管理者とgiscusのみが実施できるようにするために、Announcementsカテゴリを利用することを推奨します。

Discussionの検索時にgiscusはこのカテゴリのみを検索します

機能

有効にしたい機能を選択してください。

コメントの前にリアクションを表示する

Discussionのメタデータは定期的に親画面に送信されます。詳細はこのオプションを有効にしてブラウザのコンソールウィンドウを開くことで確認できます。詳細はドキュメントをご参照ください。

コメント入力ボックスはコメントの上に配置されるため、ユーザーはディスカッションの一番下までスクロールせずにコメントを残すことができます。

コメントの読み込みは、ユーザーがコメントコンテナの近くをスクロールした後に実行されます。 これは、 loading="lazy"を<iframe>要素に追加することで実行されます。

テーマ

Webサイトに適したテーマを選択してください。良いものが見つからない場合は、自分で作成して私たちに送信することもできます。

giscusを有効にする

下記の <script> コードタグをお使いのWebサイトのコメントを表示したい場所に追加してください。もし、giscusクラスを持つ要素が存在する場合、giscusは当該要素にコメントを表示します。

リポジトリやカテゴリを構成していません。 これらのフィールドの値は、入力するまで表示されません。
<script src="https://giscus.app/client.js"
        data-repo="[リポジトリを記述]"
        data-repo-id="[リポジトリIDを記述]"
        data-category="[カテゴリ名を記述]"
        data-category-id="[カテゴリ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="ja"
        crossorigin="anonymous"
        async>
</script>

.giscus と .giscus-frame セレクタを利用することで、レイアウトをカスタマイズすることができます。

giscusを利用する場合は、giscusにGitHubスター🌟を付けたり、giscusをリポジトリのトピックに追加したりしていただけると幸いです! 🎉

上級者向け機能

追加の設定(特定オリジンのみの許可など)については上級者向け機能ガイドをご参照ください。

giscusをReactやVue、Svelteで利用する場合はgiscusコンポーネントライブラリをご参照ください。

移行

もし以前GitHub Issuesを利用したツール(utterancesやgitalkなど)を使用していた場合、既存のIssueをDiscussionに移管する事が出来ます。移管後はDiscussionタイトルが連携設定に基づき正しく設定されていることを確認してください。その後は、giscusが自動的にDiscussionを利用します。

giscusを利用しているサイト

貢献するには

CONTRIBUTING.mdをご参照ください。

試してみる 👇👇👇

Powered by Vercel