添加评论系统¶
Material for MkDocs 允许您通过使用 theme extension 轻松地将您选择的第三方评论系统添加到任何页面的页脚。作为示例，我们将集成 Giscus，它是开源的、免费的，并使用 GitHub 讨论作为后端。
自定义¶
Giscus 集成¶
在您可以使用 Giscus 之前，需要完成以下步骤：
- 安装 Giscus GitHub App 并授予对应于应作为 GitHub 讨论托管评论的存储库的访问权限。请注意，这可以是与您的文档不同的存储库。
-
访问 Giscus 并通过他们的配置工具生成代码片段 以加载评论系统。复制代码片段以便在下一步使用。生成的代码片段应类似于以下内容：
comments.html 部分（默认是空的）是添加 Giscus 生成的代码片段的最佳位置。按照 theme extension 的指南，并用以下内容 override the comments.html partial：
{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- 在此插入生成的代码片段 -->
<!-- 同步 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 设置主题
giscus.setAttribute("data-theme", theme) // (1)!
}
// 在文档加载后注册事件处理程序
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"
// 指示 Giscus 更改主题
var frame = document.querySelector(".giscus-frame")
frame.contentWindow.postMessage(
{ giscus: { setConfig: { theme } } },
"https://giscus.app"
)
}
})
})
</script>
{% endif %}
- 此代码块确保当调色板设置为
slate时， Giscus 使用深色主题。请注意，有多种深色主题可供选择，因此您可以根据自己的喜好进行更改。
用您在上一步中通过 Giscus 配置工具生成的代码片段替换高亮行。如果您从上面复制了代码片段，则可以通过将 comments 前置属性设置为 true 来启用页面上的评论：
如果您希望为整个文件夹启用评论，可以使用 built-in meta plugin。