跳轉至

留言系統

靜態網站本身沒有後端，但可以透過第三方服務，在任何頁面的底部加上留言系統。這一頁以 Giscus 為例：它是開源、免費的服務，以 GitHub Discussions 作為儲存留言的後端。

沒有內建，要自己整合

Zensical 沒有原生的留言功能，做法是覆寫模板中預留的 comments.html（預設是空的）。

準備 Giscus

  1. 安裝 Giscus GitHub App，並授權給用來存放留言（以 GitHub Discussions 形式）的程式庫。這個程式庫可以不是你放文件的那一個。
  2. 到 Giscus 網站，用它的設定工具產生一段程式碼，大致像這樣：
<script
  src="https://giscus.app/client.js"
  data-repo="<username>/<repository>"
  data-repo-id="..."
  data-category="..."
  data-category-id="..."
  data-mapping="pathname"
  data-reactions-enabled="1"
  data-emit-metadata="1"
  data-theme="light"
  data-lang="zh-TW"
  crossorigin="anonymous"
  async
>
</script>

覆寫 comments.html

啟用 custom_dir（見 網站客製化），建立 overrides/partials/comments.html，並把 Giscus 產生的程式碼貼進去。下面的版本還會讓 Giscus 的主題跟著深色模式同步切換：

overrides/partials/comments.html
{% if page.meta.comments %}
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>

  <!-- 在這裡貼上 Giscus 產生的程式碼 -->

  <!-- 讓 Giscus 主題與色彩配置同步 -->
  <script>
    var giscus = document.querySelector("script[src*=giscus]")

    // 第一次載入時設定主題
    var palette = __md_get("__palette")
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate"
        ? "transparent_dark"
        : "light"
      giscus.setAttribute("data-theme", theme)
    }

    // 頁面載入後註冊事件，切換色彩時通知 Giscus
    document.addEventListener("DOMContentLoaded", function() {
      var ref = document.querySelector("[data-md-component=palette]")
      ref.addEventListener("change", function() {
        var palette = __md_get("__palette")
        if (palette && typeof palette.color === "object") {
          var theme = palette.color.scheme === "slate"
            ? "transparent_dark"
            : "light"

          var frame = document.querySelector(".giscus-frame")
          frame.contentWindow.postMessage(
            { giscus: { setConfig: { theme } } },
            "https://giscus.app"
          )
        }
      })
    })
  </script>
{% endif %}

當色彩配置是 slate（深色）時，Giscus 會使用深色主題。Giscus 有多種深色主題，可以自行更換。

在頁面啟用留言

用 front matter 的 comments 屬性，逐頁決定要不要顯示留言：

---
comments: true
---

# 頁面標題

沒有設定的頁面不會出現留言區。

總結

步驟 做法
1 安裝 Giscus App、產生程式碼
2 建立 overrides/partials/comments.html 並貼上程式碼
3 頁面 front matter 加上 comments: true

離線建置請關閉留言

留言系統需要連網，用於離線使用的建置請不要啟用。

參考資料