跳轉至

資料隱私（Cookie 同意）

網站使用 Google Analytics 等第三方服務前，依照 GDPR 等法規，需要先取得使用者同意。Zensical 內建了原生、可擴充的 Cookie 同意表單，會在送出任何第三方請求之前先詢問使用者。

[project.extra.consent]
title = "Cookie 同意"
description = """
  我們使用 Cookie 來辨識您重複的造訪與偏好，並衡量文件的成效，
  以及使用者是否找得到想找的內容。經過您的同意，
  您就是在協助我們把文件做得更好。
"""

description 內可以放任意 HTML 標籤，例如連結到服務條款或隱私權政策。

屬性 說明
title 必填。表單標題，不可為空字串
description 必填。標題下方的說明，可包含 HTML
cookies 新增自訂 Cookie，或修改內建 Cookie 的名稱與預設勾選狀態
actions 顯示哪些按鈕，以及順序

使用者第一次造訪網站時，就會看到同意表單。如果已經設定了 Google Analytics，表單會自動加上讓使用者關閉它的選項；而使用者若沒有接受 analytics Cookie，「這一頁對您有幫助嗎？」評分元件也不會顯示。

內建的 Cookie 有兩個，預設都是勾選的：

  • analytics：Google Analytics
  • github：GitHub

每個 Cookie 用唯一的識別字當作鍵，值可以是字串（名稱），或包含 name 與 checked 的表：

# 只改名稱
[project.extra.consent.cookies]
analytics = "自訂名稱"

# 改名稱並預設不勾選
[project.extra.consent.cookies]
analytics.name = "Google Analytics"
analytics.checked = false

# 新增自訂 Cookie
[project.extra.consent.cookies]
analytics.name = "Google Analytics"
analytics.custom = "自訂 Cookie"

新增自訂 Cookie 時，要把 analytics 加回來

只要定義了 cookies，就必須明確把 analytics 也寫進去，否則 Google Analytics 不會被觸發。

設定按鈕

同意表單有三種按鈕：

  • accept：接受所選的 Cookie
  • reject：拒絕所有 Cookie
  • manage：管理設定
[project.extra.consent]
actions = [
  "accept",
  "manage",
]

如果 actions 裡沒有 manage，設定選項會一直顯示。

讓使用者隨時能修改設定

依照 GDPR，使用者必須能隨時修改 Cookie 設定。做法是在版權宣告加上一個連結到 #__consent 的連結：

[project]
copyright = """
  Copyright © 2026 唯客學院 –
  <a href="#__consent">變更 Cookie 設定</a>
"""

使用者接受或拒絕後，頁面會重新載入，可以用 JavaScript 查詢結果：

docs/js/consent.js
var consent = __md_get("__consent")
if (consent && consent.custom) {
  /* 使用者接受了 Cookie */
} else {
  /* 使用者拒絕了 Cookie */
}

別忘了在 extra_javascript 載入這個檔案。

總結

想做的事 設定
啟用同意表單 [project.extra.consent] 的 title、description
改 Cookie 名稱／預設狀態 consent.cookies
自訂按鈕 consent.actions
讓使用者改設定 版權宣告加入 <a href="#__consent">

參考資料