Add AI documentation skills

.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/setup/adding-a-comment-system.md

@@ -0,0 +1,113 @@
+# 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