@giscusgiscus

giscus

由 GitHub Discussions 驅動的留言系統。讓訪客借助 GitHub 在你的網站上留言和留下反應吧！本專案很大一部份是受 utterances 啟發。

注意：
giscus 仍活躍開發中。GitHub 也還在活躍地開發 Discussions 及其 API。因此，一些 giscus 的功能可能將隨時間而無法使用或改變。

運作原理

giscus 載入時，會使用 GitHub Discussions 搜尋 API 根據選定的搜尋對應方式（如 URL、pathname、<title> 等）來搜尋與目前頁面相關的 discussion。如果找不到符合的 discussion，giscus bot 就會在第一次有人留言或反應時自動建立一則 discussion。

如要留言，訪客必須按照 GitHub OAuth 流程授權 giscus app 代表他發文。或者訪客也可以直接在 GitHub Discussion 裡面留言。你可以在 GitHub 上管理留言。

設定

語言

選擇 giscus 的顯示語言。找不到你的語言嗎？來貢獻一個！

儲存庫

選擇 giscus 要連結的儲存庫。請確保：

  1. 此儲存庫是公開的，否則訪客將無法查看 discussion。
  2. 已安裝 giscus 應用程式，否則訪客將無法留言或回應。
  3. 你要連結的儲存庫已啟用 Discussions 功能。

一個公開的 (public) GitHub 儲存庫。Discussion 將連結到此儲存庫。

頁面 ↔️ discussion 對應方式

選擇頁面與嵌入的 discussion 之間的對應方式。

giscus 將尋找標題中包含頁面網址路徑名稱部分的 discussion。

giscus 將尋找標題中包含頁面網址的 discussion。

giscus 將搜尋標題中包含頁面的 <title> 標籤的 discussion。

giscus 將搜尋標題中包含頁面的 <meta property="og:title"> 標籤的 discussion。

giscus 將搜尋標題中包含特定字串的 discussion。

giscus 將按編號載入特定的 discussion。此選項不支援自動建立 discussion。

當有多個具有相似標題的討論時，避免由於 GitHub 的模糊搜索方法而導致的不匹配。請閱讀說明文件以了解更多。

Discussion 分類

選擇新 discussions 所在的分類。 建議使用公告 (announcements) 類型的分類，以確保新 discussion 只能由儲存庫維護者和 giscus 建立。

當搜尋符合的 discussion 時，giscus 將只搜尋該分類。

功能

選擇是否啟用某些功能。

Discussion 主文上的反應將會顯示在留言前。

Discussion 的中繼資料將定期被傳送到父頁面（即嵌入 giscus 的頁面）。您可以嘗試啟用此功能，並在此頁打開瀏覽器主控台。請閱讀說明文件以了解更多。

留言輸入框會放在留言的上方，如此一來使用者不必捲動到討論底部才能撰寫留言。

使用者往下捲動至留言區的容器附近才會開始載入留言。這是透過在 <iframe> 元素中加上 loading="lazy" 達成的。

佈景主題

選擇適合你網站的佈景主題。找不到適合的？來貢獻一個！

啟用 giscus

在你想放置留言區的位置加上下列的 <script> 標籤。但如果已經存在使用 giscus class 的元素，留言區會出現在那邊。

您尚未配置儲存庫和/或分類。 在您填寫這些欄位之前，不會顯示這些欄位的值。
<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="zh-TW"
        crossorigin="anonymous"
        async>
</script>

你可以在嵌入的頁面中使用 .giscus 和 .giscus-frame css 選擇器來自訂容器樣式。

如果你使用了 giscus，請考慮在 GitHub 上 star 🌟 giscus 並為你的repo 加上 giscus topic！🎉

進階用法

你可以依照進階用法指南添加其他設定（例如允許特定來源）。

要在 React、Vue 和 Svelte 中使用 giscus，請查看 giscus components。

轉移

如果你曾經使用過其它利用 GitHub Issue 的留言系統（如 utterances、gitalk），你可以把已有的 issue 轉換成 discussion。轉換後，只要確保 discussion 標題與頁面的對應關係正確，giscus 就會自動使用這些 discussion。

正使用 giscus 的網站

貢獻

請查看 CONTRIBUTING.md。

試試看 👇👇👇

Powered by Vercel