給 Hugo 網站加入 Giscus 留言板

開頭
#

在架設 Hugo 靜態網站時，最讓人頭痛的其中一件事就是：「怎麼加入留言功能呢？」🤔 常見的留言板方案可能需要載入肥大的第三方腳本，而像是 Valine 或 Artalk 等則需要自己額外架設後端伺服器。

而今天這篇要介紹的 Giscus 簡直就是大救星！它是基於 GitHub Discussions 所打造的留言系統，具備以下超棒的優點：

完全免費、無廣告：依託 GitHub 平台，不需要額外付費租用伺服器。
資料掌握在自己手上：所有的留言都會同步儲存在您的 GitHub Repository 的 Discussions 中。

第一步：準備 GitHub 倉庫與啟用 Discussions
#

可以新建一個專門存放留言的 Repo，也可以使用現有的您的 Hugo 網站原始碼 repo，但：

該 GitHub Repo 必須是 公開的 (Public)。（如果是 Private 的話訪客會無法讀取與留言唷！）
必須啟用 Discussions 功能：
- 進入要使用的 GitHub Repo 頁面。
- 點擊上方導覽列的 Settings。
- 在左側選單的 Features 區塊中，找到 Discussions 並將其打勾啟用。

第二步：安裝 Giscus GitHub App
#

為了讓 Giscus 能夠存取您的 Discussions，需要在倉庫中安裝官方的 GitHub App：

前往 Giscus 官方網站進行設定。
在網頁中下方找到 安裝 giscus 應用程式 的連結（或是直接點擊這裡前往安裝）。
選擇您要授權的 GitHub 帳號或組織，並選擇 Only select repositories，指定您放網站的那個 Repo。
點擊 Install & Authorize 完成安裝！🎉

示範：

第三步：取得 Giscus 配置參數
#

回到 Giscus 官網，往下填寫設定：

倉庫：填入 GitHub用戶名/倉庫名（例如：yourname/my-blog）。
頁面與 Discussions 的對應方式：建議選擇 pathname（網址路徑），這樣每個頁面就會對應到一個獨立的 Discussion，但我是選 title，因為好看啊！
Discussion 分類 (Category)：建議選擇 Announcements。
主題 (Theme)：可以選擇 preferred_color_scheme，但我是選 light ，因為等下的步驟中，我會直接在留言板背景插入一個白色方塊避免顏色被吃掉！
網頁下方就會自動生成一段專屬於您的 <script> 設定碼，長得會像這樣：

<!-- 這只是範例，不要使用這段程式碼，請依照自己拿到的程式碼為準！ -->

<script src="https://giscus.app/client.js"
        data-repo="yourname/my-blog"
        data-repo-id="R_kgD..."
        data-category="Announcements"
        data-category-id="DIC_kwD..."
        data-mapping="title"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light"
        data-lang="zh-TW"
        crossorigin="anonymous"
        async>
</script>

第四步：整合到 Hugo 佈景主題中
#

接下來要把這段程式碼放進 Hugo 的文章模板裡。不同的佈景主題做法可能略有不同，但一般標準的做法是建立或修改 Partial 模板。

我使用的是 Blowfish Themes，要修改的檔案位於 themes/blowfish/layouts/partials/article-comments.html，在這裡使用這個檔案示範。

0. 在設定檔中開啟 `showComments` 選項
#

在 Hugo 的設定檔，例如 params.toml 等等，打開留言選項。

# config/_default/params.toml
[article]
    ### 其他設定略
    showComments = true

1. 建立留言板 Partial 檔案
#

在您主題資料夾底下的 layouts/partials/ 目錄中，建立一個名為 article-comments.html 的檔案，覆蓋 Blowfish 預設的留言板模版，建立自己的留言板模版：

{{ if and
  (strings.HasPrefix .File.Path "posts/")
  (.Params.showComments | default (site.Params.article.showComments | default false))
}}
  {{ if templates.Exists "partials/comments/giscus.html" }}
    <div class="pt-8">
      <hr>
      <br>
      {{/* 標題與說明文字區塊 */}}
      <div class="mb-6 flex flex-col gap-1">
        {{/* 標題與裝飾圓點 */}}
        <div class="flex items-center gap-2">
          <h2 class="mt-8 text-2xl font-extrabold mb-10">
            留言區
          </h2>
          <span class="h-2 w-2 rounded-full bg-primary-500 inline-block"></span>
        </div>
        
        {{/* 輔助說明文字 */}}
        <p class="text-sm text-neutral-500 dark:text-neutral-400">
          歡迎針對文章內容提出想法或交流！點擊下方按鈕即可載入 Giscus 留言板，使用 GitHub 登入即可留言喔！
        </p>
      </div>

      {{/* 留言載入與按鈕區塊 */}}
      <div class="pt-2 flex flex-col items-center justify-center min-h-[120px]" id="comments-wrapper">
        {{/* 載入留言按鈕 */}}
        <button 
          type="button"
          id="load-comments-button"
          onclick="loadGiscusComments()"
          class="px-6 py-3 rounded-lg border border-neutral-300 dark:border-neutral-700 bg-neutral-100 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-200 hover:bg-neutral-200 dark:hover:bg-neutral-700 transition-colors font-medium text-base focus:outline-none">
          載入留言板
        </button>
        
        {{/* 留言載入容器：設定固定的純白背景與深色文字，不會隨主題變黑 */}}
        <div id="comments-container" class="w-full p-4 rounded-xl bg-white border border-neutral-200 text-neutral-900 shadow-sm"></div>
        {{ partial "comments/giscus.html" . }}
      </div>
    </div>
  {{ else }}
    {{ warnf "[BLOWFISH] Comments are enabled for %s but no comments partial exists." .File.Path }}
  {{ end }}
{{ end }}

註：模版中我只允許路徑是 /posts/* 的文章，以及有啟用 showComments，留言板才會顯示。

註：這裡的 loadGiscusComments() ，我會在下方的 giscus.html 中實作動態插入 <script> 標籤的 JS 邏輯，達到點擊按鈕後才非同步載入 Giscus 的效果～

小技巧：有些熱門的 Hugo 主題（例如 Hugo PaperMod、DoIt、FixIt 等）本身就在內建設定檔裡原生支援 Giscus 了！您只需要打開主題的 hugo.toml（或 params.toml），找到 [params.giscus] 區塊，把對應的 repo、repo-id、category-id 填進去就可以直接啟用，完全不需要自己手動刻模板唷！因主題而異，可以去檢查看看自己的 Hugo 主題支不支援。

2. 建立 giscus 專屬模版
#

在 layouts/partials/ 新增一個資料夾 comments，並在裡面加入 giscus.html，注意！這裡並不是直接貼入 giscus 生成的腳本，所以請替換為自己的參數。

<script>
/**
 * 延遲載入 Giscus 留言系統
 */
let giscusLoading = false;
let giscusLoaded = false;

function loadGiscusComments() {
  const button = document.getElementById('load-comments-button');
  const container = document.getElementById('comments-container');

  if (!container || giscusLoading || giscusLoaded) {
    return;
  }

  // 防止重複建立 Giscus 腳本
  if (document.getElementById('giscus-script')) {
    return;
  }

  giscusLoading = true;

  if (button) {
    button.disabled = true;
    button.textContent = '正在載入留言板…';
  }

  const script = document.createElement('script');
  script.id = 'giscus-script';
  script.src = 'https://giscus.app/client.js';
  script.async = true;
  script.crossOrigin = 'anonymous';

  script.setAttribute('data-repo', '請替換');
  script.setAttribute('data-repo-id', '請替換');
  script.setAttribute('data-category', '請替換');
  script.setAttribute('data-category-id', '請替換');
  script.setAttribute('data-mapping', 'title');
  script.setAttribute('data-strict', '0');
  script.setAttribute('data-reactions-enabled', '1');
  script.setAttribute('data-emit-metadata', '0');
  script.setAttribute('data-input-position', 'bottom');
  script.setAttribute('data-theme', 'light');
  script.setAttribute('data-lang', 'zh-TW');

  script.onload = function () {
    giscusLoading = false;
    giscusLoaded = true;

    if (button) {
      button.style.display = 'none';
    }
  };

  script.onerror = function () {
    giscusLoading = false;
    giscusLoaded = false;

    script.remove();

    if (button) {
      button.disabled = false;
      button.textContent = '載入失敗，請重試';
    }
  };

  container.appendChild(script);
}
</script>

第五步：本地測試與部署
#

設定完成後，可以在本地端執行指令來預覽效果：

hugo server

打開瀏覽器前往文章頁面，捲動到最下方，如果順利看到 Giscus 的登入按鈕與留言輸入框，就代表大功告成啦！

結尾
#

本部落格一樣有插入 giscus 留言板，在文章頁面最下方，歡迎留言！

開頭 #

第一步：準備 GitHub 倉庫與啟用 Discussions #

第二步：安裝 Giscus GitHub App #

第三步：取得 Giscus 配置參數 #

第四步：整合到 Hugo 佈景主題中 #

0. 在設定檔中開啟 showComments 選項 #

1. 建立留言板 Partial 檔案 #

2. 建立 giscus 專屬模版 #

第五步：本地測試與部署 #

結尾 #

相關文章