Updated comment provider integration guide

docs/setup/adding-a-comment-system.md

@@ -4,40 +4,83 @@ template: overrides/main.html
 
 # Adding a comment system
 
-Material for MkDocs is natively integrated with [Disqus], a comment system that
-provides a wide range of features like social integrations, user profiles, as
-well as spam and moderation tools. Of course, other comment systems can be
-integrated, too.
+Material for MkDocs allows to easily add the third-party comment system of your
+choice to the footer of every page by using [theme extension]. As an example,
+we'll be integrating [Disqus] a wildly popular comment provider, but others
+can be integrate with the same principles
 
   [Disqus]: https://disqus.com/
 
-## Configuration
-
-### Disqus
-
-[:octicons-tag-24: 1.1.0][Disqus support] ·
-:octicons-milestone-24: Default: _none_
-
-First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`. Then, to
-integrate Material for MkDocs with [Disqus], create an account and a site
-giving you a [shortname], and add it to `mkdocs.yml`:
-
-``` yaml
-extra:
-  disqus: <shortname>
-```
-
-This will insert a comment system on every page, except the index page.
-
-  [Disqus support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
-  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
-  [shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
-
 ## Customization
 
-### Selective integration
+### Disqus integration
 
-When [Metadata] is enabled, Disqus can be enabled or disabled for a document
+In order to integrate a third-party comment provider offering a JavaScript-based
+solution, follow the guide on [theme extension], copy the contents from the
+[`page-footer.html`][page-footer partial] partial and create a file
+at the same location in the `overrides` folder:
+
+=== ":octicons-file-code-16: overrides/partials/page-footer.html"
+
+    ``` html
+    <!-- Add copied contents from original page-footer.html here -->
+
+    <!-- Get setting from mkdocs.yml, but allow page-level overrides -->
+    {% set disqus = config.extra.disqus %}
+    {% if page and page.meta and page.meta.disqus is string %}
+      {% set disqus = page.meta.disqus %}
+    {% endif %}
+
+    <!-- Inject Disqus into current page -->
+    {% if not page.is_homepage and disqus %}
+      <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
+      <div id="disqus_thread"></div>
+      <script>
+        var disqus_config = function() {
+          this.page.url = "{{ page.canonical_url }}"
+          this.page.identifier =
+            "{{ page.canonical_url | replace(config.site_url, '') }}" // (1)
+        }
+
+        /* Set up for the first time */
+        if (typeof DISQUS === "undefined") {
+          var script = document.createElement("script")
+          script.async = true
+          script.src = "https://{{ disqus }}.disqus.com/embed.js"
+          script.setAttribute("data-timestamp", Date.now())
+
+          /* Inject script tag */
+          document.body.appendChild(script)
+
+        /* Set up on navigation (instant loading) */
+        } else {
+          DISQUS.reset({
+            reload: true,
+            config: disqus_config
+          })
+        }
+      </script>
+    {% endif %}
+    ```
+
+    1.  Ensure you've set [`site_url`][site_url] in `mkdocs.yml`.
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra:
+      disqus: <shortname> # (1)
+    ```
+
+    1.  Add your Disqus [shortname] here.
+
+  [theme extension]: ../customization.md#extending-the-theme
+  [page-footer partial]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/page-footer.html
+  [shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
+
+#### on a single page
+
+When [Metadata] is enabled, Disqus can be enabled or disabled for a single page
 with custom front matter. Add the following lines at the top of a Markdown file:
 
 === ":octicons-check-circle-fill-16: Enabled"
@@ -63,20 +106,3 @@ with custom front matter. Add the following lines at the top of a Markdown file:
     ```
 
   [Metadata]: extensions/python-markdown.md#metadata
-
-### Other comment systems
-
-In order to integrate another JavaScript-based comment system provider, you can
-[extend the theme], create a new `main.html` in `overrides` and [override the
-`disqus` block][overriding blocks]:
-
-``` html
-{% extends "base.html" %}
-
-{% block disqus %}
-  <!-- Add custom comment system integration here -->
-{% endblock %}
-```
-
-  [extend the theme]: ../customization.md#extending-the-theme
-  [overriding blocks]: ../customization.md#overriding-blocks

docs/setup/changing-the-language.md

@@ -184,7 +184,7 @@ the guide on [theme extension] and create a new partial in the `overrides`
 folder. Then, import the [translations] of the language as a fallback and only
 adjust the ones you want to override:
 
-=== ":octicons-file-code-16: partials/languages/custom.html"
+=== ":octicons-file-code-16: overrides/partials/languages/custom.html"
 
     ``` html
     <!-- Import translations for language and fallback -->

docs/setup/setting-up-site-analytics.md

@@ -291,7 +291,7 @@ JavaScript-based tracking solution, just follow the guide on [theme extension]
 and create a new partial in the `overrides` folder. The name of the partial is
 used to configure the custom integration via `mkdocs.yml`:
 
-=== ":octicons-file-code-16: partials/integrations/analytics/custom.html"
+=== ":octicons-file-code-16: overrides/partials/integrations/analytics/custom.html"
 
     ``` html
     <script>
@@ -331,7 +331,7 @@ used to configure the custom integration via `mkdocs.yml`:
 
 ### Custom site feedback
 
-A custom feedback widget integation just needs to process the events that are
+A custom feedback widget integration just needs to process the events that are
 generated by users interacting with the feedback widget with the help of some
 [additional JavaScript]:
 
@@ -342,9 +342,12 @@ generated by users interacting with the feedback widget with the help of some
     feedback.addEventListener("submit", function(ev) {
       ev.preventDefault()
 
-      /* Retrieve and send feedback */
+      /* Retrieve page and feedback value */
       var page = document.location.pathname
       var data = ev.submitter.getAttribute("data-md-value")
+
+      /* Send feedback value */
+      console.log(page, data)
     })
     ```
 

docs/setup/setting-up-site-search.md

@@ -127,7 +127,7 @@ The following configuration options are supported:
           prebuild_index: true
     ```
 
-    Note that this configuration option was deprecated, as the [new search
+    Note that this configuration option was removed, as the [new search
     plugin] generates up to [50% smaller] search indexes, doubling search
     performance.