MaterialX 接入 Giscus 评论系统
Giscus 是一个基于 GitHub Discussions 的轻量级评论系统。它让你可以在静态网站(如博客、文档站)中嵌入评论区,而所有评论数据实际上都存储在你指定的 GitHub 仓库的讨论区里。
这里记录一下个人的 MkDocs(基于 MaterialX 主题)站点,在集成 giscus 评论的同时,并让它使用 data-mapping="number" 精确与指定的 Discussion 一一匹配对应。核心思路是:覆盖主题的 comments.html 模板,在页面 front matter 中为每篇文章手动指定一个 GitHub Discussion 编号,然后让 giscus 脚本动态读取这个编号作为 data-term。
1. 获取 Discussion 编号¶
Giscus 的 number 映射模式依赖一个明确的数字 ID。你需要先在 GitHub 仓库的 Discussions 中为你的文档页面创建(或找到)对应的讨论帖,并记下其编号。
编号就是讨论帖 URL 末尾的数字。例如 https://github.com/owner/repo/discussions/42,编号就是 42。
2. 配置 MkDocs 主题覆盖¶
在 mkdocs.yml 中确保启用了 custom_dir:
theme:
name: material
custom_dir: overrides
然后在 overrides/partials/comments.html 文件中编写逻辑。由于 MaterialX 使用 Jinja2 模板,你可以根据页面元数据(front matter)来条件化地输出 giscus 脚本。
3. 编写 comments.html 模板¶
仅当页面 front matter 中存在 discussion_number 时才渲染 giscus 评论区(使用 number 映射),否则什么都不输出。关键点:data-term 的值必须动态填入 {{ page.meta.discussion_number }},这是 number 映射生效的必要条件。
{% if page.meta and page.meta.discussion_number %}
<h2 id="__comments">评论</h2>
<script src="https://giscus.app/client.js"
data-repo="你的用户名/你的仓库名"
data-repo-id="你的仓库ID"
data-mapping="number"
data-term="{{ page.meta.discussion_number }}"
data-strict="0"
data-reactions-enabled="1"
data-emit-metadata="0"
data-input-position="bottom"
data-theme="preferred_color_scheme"
data-lang="zh-CN"
crossorigin="anonymous"
async>
</script>
<!-- Synchronize Giscus theme with palette -->
<script>
var giscus = document.querySelector("script[src*=giscus]")
// Set palette on initial load
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
var theme = palette.color.scheme === "slate"
? "transparent_dark"
: "light"
// Instruct Giscus to set theme
giscus.setAttribute("data-theme", theme)
}
// Register event handlers after documented loaded
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"
// Instruct Giscus to change theme
var frame = document.querySelector(".giscus-frame")
frame.contentWindow.postMessage(
{ giscus: { setConfig: { theme } } },
"https://giscus.app"
)
}
})
})
</script>
{% endif %}
或者可以考虑,如果页面 front matter 中有 discussion_number,则使用 number 映射;否则可以回退到 pathname 或直接不显示,按需修改就行,不会写也可以直接问 AI。
4. 在 Markdown 页面中指定编号¶
在你的 Markdown 文件(如 docs/index.md)的 front matter 中,添加你之前记下的讨论编号:
---
title: 我的文档页面
comments: true
discussion_number: 42
---
最后,重新构建站点。
欢迎留言评论