--- template: overrides/main.html --- # 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> ``` You can either integrate [Giscus] on every page by overriding the `main.html` template, or create a new template (e.g. `blog.html`) to extend from `main.html` which includes the comment system, so you can decide for each page whether you want to allow comments or not. In order to integrate [Giscus], follow the guide on [theme extension] and [override the `content` block][overriding blocks], extending the default by calling the `super()` function at the beginning of the block: ``` html hl_lines="8" {% extends "base.html" %} {% block content %} {{ super() }} <!-- Giscus --> <h2 id="__comments">{{ lang.t("meta.comments") }}</h2> <!-- Replace with generated snippet --> <!-- Reload on palette change --> <script> var palette = __md_get("__palette") if (palette && typeof palette.color === "object") if (palette.color.scheme === "slate") { var giscus = document.querySelector("script[src*=giscus]") giscus.setAttribute("data-theme", "dark") // (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" ? "dark" : "light" /* Instruct Giscus to change theme */ var frame = document.querySelector(".giscus-frame") frame.contentWindow.postMessage( { giscus: { setConfig: { theme } } }, "https://giscus.app" ) } }) }) </script> {% endblock %} ``` 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 extended `main.html`, you should now see the [Giscus] comment system at the bottom of each page. If you created a new, separate template, you can enable Giscus by [setting the page template] via front matter. [Giscus GitHub App]: https://github.com/apps/giscus [theme extension]: ../customization.md#extending-the-theme [overriding blocks]: ../customization.md#overriding-blocks [setting the page template]: ../reference/index.md#setting-the-page-template