跳转至

Giscus

Giscus 是一個利用 GitHub Discussions API 的留言系統，優點是完全免費、開源，且沒有廣告。

https://giscus.app/zh-TW

隨便建立一個獨立的 GitHub Repo（例如命名為 my-blog-comments），專門用來存放留言。

1. 前置作業

  • 確保你的專案 Repo 是 公開的 (Public)。

  • 在 GitHub Repo 的 Settings -> Features 中勾選 Discussions。

  • 得先安裝 giscus https://github.com/apps/giscus

  • 到 giscus.app 依照指示填入你的 儲存庫： "Account/Repo name"，往下滾取得產出的配置資訊（如 data-repo-id 等）。

1.1. 網址路徑來對應留言

Giscus 預設通常是用 pathname（網址路徑）來對應留言。

  • 只要你的 MkDocs 網頁路徑是固定的，留言就會精準地出現在該出現的頁面。

  • 不影響：就算你的 MkDocs 源碼在 Repo A，留言存在 Repo B，只要 data-repo 指向 B，運作起來完全沒問題。

2. 修改 MkDocs 模板

MkDocs 的留言板通常需要加在文章底部的模板中。如果你使用的是最受歡迎的 Material for MkDocs 主題，請按照以下步驟操作：

  1. 在專案根目錄建立一個資料夾：overrides/。

  2. 在裡面建立一個檔案：main.html。

  3. 貼入以下代碼（將其中的 data-repo 等資訊替換成你在 Giscus 官網取得的參數）：

{% extends "base.html" %}

{% block content %}
  {{ super() }}

  <h2 id="__comments">💬 留言區</h2>

  <script src="https://giscus.app/client.js"
          data-repo="你的帳號/你的專案名"
          data-repo-id="R_kgD..."
          data-category="Announcements"
          data-category-id="DIC_..."
          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>
{% endblock %}

3. 更新 mkdocs.yml

告訴 MkDocs 去讀取你的自定義模板：

theme:
  name: material
  custom_dir: overrides  # 讓 MkDocs 抓取剛才寫的 main.html

4. 關閉留言區

{# 如果 meta 裡沒有設定 comments 為 false，就顯示留言區 #}
{% if not (page.meta and page.meta.comments == false) %}
  <h2 id="__comments">💬 留言區</h2>
  {% endif %}

  • 平時：你什麼都不用寫，每一篇都會有留言區。

  • 想關閉時（例如首頁、關於我）：在 .md 最上方寫：

---
comments: false
---