1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-23 04:44:56 +01:00
mkdocs-material/docs/setup/adding-a-comment-system.md
2023-09-22 14:35:20 +02:00

114 lines
3.7 KiB
Markdown

# Adding a comment system
Material for MkDocs allows to easily add the third-party comment system of your
choice to the footer of any page by using [theme extension]. As an example,
we'll be integrating [Giscus], which is Open Source, free, and uses GitHub
discussions as a backend.
[Giscus]: https://giscus.app/
## Customization
### Giscus integration
Before you can use [Giscus], you need to complete the following steps:
1. __Install the [Giscus GitHub App]__ and grant access to the repository
that should host comments as GitHub discussions. Note that this can be a
repository different from your documentation.
2. __Visit [Giscus] and generate the snippet__ through their configuration tool
to load the comment system. Copy the snippet for the next step. The
resulting snippet should look similar to this:
``` html
<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="en"
crossorigin="anonymous"
async
>
</script>
```
The [`comments.html`][comments] partial (empty by default) is the best place to
add the snippet generated by [Giscus]. Follow the guide on [theme extension]
and [override the `comments.html` partial][overriding partials] with:
``` html hl_lines="3"
{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Insert generated snippet here -->
<!-- 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) // (1)!
}
// 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 %}
```
1. This code block ensures that [Giscus] renders with a dark theme when the
palette is set to `slate`. Note that multiple dark themes are available,
so you can change it to your liking.
Replace the highlighted line with the snippet you generated with the [Giscus]
configuration tool in the previous step. If you copied the snippet from above,
you can enable comments on a page by setting the `comments` front matter
property to `true`:
``` yaml
---
comments: true
---
# Page title
...
```
If you wish to enable comments for an entire folder, you can use the
[built-in meta plugin].
[Giscus GitHub App]: https://github.com/apps/giscus
[theme extension]: ../customization.md#extending-the-theme
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
[overriding partials]: ../customization.md#overriding-partials
[built-in meta plugin]: ../plugins/meta.md