Added documentation for feedback widget

docs/setup/changing-the-colors.md

@@ -199,7 +199,7 @@ The following properties must be set for each toggle:
 `icon`{ #toggle-icon }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field must point to a valid icon path referencing [any icon bundled
+    This property must point to a valid icon path referencing [any icon bundled
     with the theme][custom icons], or the build will not succeed. Some popular
     combinations:
 
@@ -211,7 +211,7 @@ The following properties must be set for each toggle:
 `name`{ #toggle-name }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field is used as the toggle's `title` attribute and should be set to a
+    This property is used as the toggle's `title` attribute and should be set to a
     discernable name to improve accessibility. It will appear on mouse hover.
 
   [palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
@@ -226,7 +226,7 @@ The following properties must be set for each toggle:
 :octicons-milestone-24: Default: _none_
 
 In order to automatically set the color palette to the user's system preference,
-a media query can be set as part of the `media` field next to the toggle
+a media query can be set as part of the `media` property next to the toggle
 definition in `mkdocs.yml`:
 
 ``` yaml

docs/setup/changing-the-language.md

@@ -117,19 +117,19 @@ The following properties must be set for each alternate language:
 `name`{ #language-name }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field is used inside the language selector as the name of the language
+    This value of this property is used inside the language selector as the
-    and must be set to a non-empty string.
+    name of the language and must be set to a non-empty string.
 
 `link`{ #language-link }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field must be set to an absolute link, which might also point to
+    This property must be set to an absolute link, which might also point to
     another domain or subdomain not necessarily generated with MkDocs.
 
 `lang`{ #language-lang }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field must contain a valid [ISO 639-1 language code] and is used for
+    This property must contain an [ISO 639-1 language code] and is used for
     the `hreflang` attribute of the link, improving discoverability via search
     engines.
 

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

@@ -7,10 +7,12 @@ template: overrides/main.html
 As with any other service offered on the web, understanding how your project
 documentation is actually used can be an essential success factor. Material for
 MkDocs natively integrates with [Google Analytics] and offers a customizable
-and extendable [cookie consent][extra.consent].
+[cookie consent][extra.consent] and a [feedback widget]
+[extra.analytics.feedback].
 
   [Google Analytics]: https://developers.google.com/analytics
   [extra.consent]: #cookie-consent
+  [extra.analytics.feedback]: #was-this-page-helpful
 
 ## Configuration
 
@@ -43,24 +45,148 @@ following lines to `mkdocs.yml`:
 
   [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
 
-#### Site search tracking
+??? question "How to measure the site search usage?"
 
-Besides basic page views, site search can also be tracked to understand better
+    Besides page views and events, [site search] can be tracked to better
-how people use your documentation and what they expect to find. To enable
+    understand how people use your documentation and what they expect to find.
-search tracking:
+    In order to enable site search tracking, the following steps are required:
 
-1.  Go to your Google Analytics __admin settings__
+    1.  Go to your Google Analytics __admin settings__
-2.  Select the property for the respective tracking code
+    2.  Select the property for the respective tracking code
-3.  Go to the __view settings__ tab.
+    3.  Go to the __view settings__ tab
-4.  Scroll down and enable __site search settings__
+    4.  Scroll down and enable __site search settings__
-5.  Set the __query parameter__ to `q`.
+    5.  Set the __query parameter__ to `q`
 
-Site search tracking is not supported with Google Analytics 4 due to the more
+    Note that currently, site search tracking is not supported with Google
-complicated manual setup. If you want to set up site search tracking yourself,
+    Analytics 4 due to the more complicated manual setup. If you want to set up
-[this tutorial][tutorial] is a good start.
+    site search tracking yourself, [this tutorial][tutorial] is a good start.
 
+  [site search]: setting-up-site-search.md
   [tutorial]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
 
+### Was this page helpful?
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-3.2.0][Insiders] ·
+:octicons-milestone-24: Default: _none_
+
+A simple [feedback widget] can be included at the bottom of each page,
+encouraging users to give instant feedback whether a page was helpful or not.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra:
+  analytics: # (1)
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >- # (2)
+            Thanks for your feedback! Help us improve this page by
+            using our <a href="..." target=_blank>feedback form</a>.
+```
+
+1.  This feature is natively integrated with [Google Analytics][extra.analytics],
+    which is why `provider` and `property` are also required. However, it's also
+    possible to provide a [custom feedback integration].
+
+2.  You can add arbitrary HTML tags to the note which is shown after the user
+    submitted the feedback, e.g. to link to a feedback form.
+
+Both properties, `title` and `ratings`, are required. Note that it's allowed to
+define more than two ratings, e.g. to implement a 1-5 star rating. Since the
+feedback widget sends data to a third-party service, it is, of course, natively 
+integrated with the [cookie consent][extra.consent] feature[^1].
+
+  [^1]:
+    If the user doesn't accept the `analytics` cookie, the feedback widget is
+    not shown.
+
+??? question "How to visualize the collected feedback ratings?"
+
+    It's quite easy to build a custom report with [Google Analytics] that will
+    quickly show you the worst- and best-rated pages of your project
+    documentation. You can generate a custom report with the following steps:
+
+    1. Go to your Google Analytics __dashboard__
+    2. Open the __customization__ panel on the left and go to __custom reports__
+    3. Create a __new custom report__ and set a custom __title__ and __name__
+    4. Add `Avg. Value` and `Total Events` to the __metric group__
+    5. Add `Event Label` to the __dimension drilldown__
+    6. Add `Event Category` to __filters__ and filter for the value __feedback__
+
+    Now, after you've saved the report and collected some feedback ratings, 
+    you'll have a list of all pages with the total number of ratings, and an
+    average rating per page. This should help you identify pages that need to
+    be improved:
+
+    [![feedback report]][feedback report]
+
+The following properties must be set for each rating:
+
+`icon`{ #feedback-rating-icon }
+
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+    This property must point to a valid icon path referencing [any icon bundled
+    with the theme][custom icons], or the build will not succeed. Some popular
+    combinations:
+
+    * :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
+    * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
+    * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
+
+`name`{ #feedback-rating-name }
+
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+    The value of this property is shown on user interaction (i.e. keyboard focus
+    or mouse hover), explaining the meaning of the rating behind the icon.
+
+`data`{ #feedback-rating-data }
+
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+    The value of this property is sent as a data value with the custom event
+    that is transmitted to Google Analytics[^2] (or any custom integration).
+
+  [^2]:
+    Note that for Google Analytics, the data value must be an integer.
+
+`note`{ #feedback-rating-note }
+
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+    The value of this property is shown after the user selected the rating.
+    It may contain arbitrary HTML tags, which is especially useful to ask the
+    user to provide more detailed feedback for the current page through a form.
+    It's also possible to pre-fill forms with the path to the current page by
+    using the `{}` placeholder, e.g.:
+
+    ``` url
+    https://github.com/<username>/<repository>/issues/new/?title=[Feedback]+{}
+    ```
+
+    In this example, when clicking the link, the user is redirected to the "new 
+    issue" form of your repository, with a pre-filled title including the path
+    of the current document, e.g.:
+
+    ```
+    [Feedback] /setup/setting-up-site-analytics/
+    ```
+
+    An alternative to GitHub issues is [Google Forms].
+
+  [feedback widget]: #feedback
+  [extra.analytics]: #google-analytics
+  [feedback report]: ../assets/screenshots/feedback-report.png
+  [custom feedback integration]: #custom-site-feedback
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [Google Forms]: https://www.google.com/forms/about/
+
 ### Cookie consent
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
@@ -75,7 +201,7 @@ following to `mkdocs.yml`:
 extra:
   consent:
     title: Cookie consent
-    description: > # (1)
+    description: >- # (1)
       We use cookies to recognize your repeated visits and preferences, as well
       as to measure the effectiveness of our documentation and whether users
       find what they're searching for. With your consent, you're helping us to
@@ -85,9 +211,9 @@ extra:
 1.  You can add arbitrary HTML tags in the `description`, e.g. to link to your
     terms of service or other parts of the site.
 
-Note that both, `title` and `description`, are required. If Google Analytics was
+Note that both, `title` and `description`, are required. If Google Analytics
-configured via `mkdocs.yml`, the cookie consent will automatically include a
+was configured via `mkdocs.yml`, the cookie consent will automatically include
-setting for the user to disable it. Furthermore, [custom cookies] can be
+a setting for the user to disable it. Furthermore, [custom cookies] can be
 integrated by using the `cookies` field:
 
 ===  "Custom cookie name"
@@ -177,6 +303,32 @@ used to configure the custom integration via `mkdocs.yml`:
   [theme extension]: ../customization.md#extending-the-theme
   [instant loading]: setting-up-navigation.md#instant-loading
 
+### Custom site feedback
+
+A custom feedback widget integation just needs to process the events that are
+generated by users interacting with the feedback widget with the help of some
+[additional JavaScript]:
+
+=== ":octicons-file-code-16: docs/javascripts/feedback.js"
+
+    ``` js
+    var feedback = document.forms.feedback
+    feedback.addEventListener("submit", function(ev) {
+      ev.preventDefault()
+
+      /* Retrieve and send feedback */
+      var page = document.location.pathname
+      var data = ev.submitter.getAttribute("data-md-value")
+    })
+    ```
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_javascript:
+      - javascripts/feedback.js
+    ```
+
 ### Custom cookies
 
 If you've customized the [cookie consent][extra.consent] and added a `custom`
@@ -199,4 +351,7 @@ JavaScript] to check whether the user accepted it:
       - javascripts/consent.js
     ```
 
+&nbsp;
+{ #feedback style="margin: 0; height: 0" }
+
   [additional JavaScript]: ../customization.md#additional-javascript

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

@@ -115,7 +115,7 @@ The following configuration options are supported:
 
 `prebuild_index`{ #search-prebuild-index }
 
-:   [:octicons-tag-24: 7.2.0][prebuilt index support] · :octicons-archive-24:
+:   [:octicons-tag-24: 5.0.0][prebuilt index support] · :octicons-archive-24:
     Deprecated · :octicons-trash-24: 8.0.0 · :octicons-milestone-24: Default:
     `false` – MkDocs can generate a [prebuilt index] of all pages during
     build time, which provides performance improvements at the cost of more

docs/setup/setting-up-the-footer.md

@@ -29,14 +29,14 @@ extra:
       link: https://twitter.com/squidfunk
 ```
 
-For each entry, the following settings are available:
+The following properties must be set for each link:
 
 `icon`{ #social-icon }
 
 :   [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24:
-    Default: _none_ · :octicons-alert-24: Required – This field must point to an 
+    Default: _none_ · :octicons-alert-24: Required – This property must contain
-    icon path referencing [any icon bundled with the theme][custom icons], or
+    a valid path to [any icon bundled with the theme][custom icons], or the
-    the build will not succeed. Some popular choices:
+    build will not succeed. Some popular choices:
 
     * :fontawesome-brands-behance: – `fontawesome/brands/behance`
     * :fontawesome-brands-docker: – `fontawesome/brands/docker`
@@ -52,7 +52,7 @@ For each entry, the following settings are available:
 `link`{ #social-link }
 
 :   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
-    This field must contain a valid relative or absolute URL including the URI 
+    This property must be set to a relative or absolute URL including the URI 
     scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
 
     === ":fontawesome-brands-twitter: Twitter"
@@ -76,8 +76,8 @@ For each entry, the following settings are available:
 `name`{ #social-name }
 
 :   [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24: 
-    Default: _domain name from_ `link`_, if available_ – This field is used as
+    Default: _domain name from_ `link`_, if available_ – This property is used
-    the link's `title` attribute and can be set to a  discernable name to
+    as the link's `title` attribute and can be set to a discernable name to
     improve accessibility:
 
     ``` yaml
@@ -114,7 +114,7 @@ copyright: Copyright © 2016 - 2020 Martin Donath
 :octicons-milestone-24: Default: `true`
 
 The footer displays a _Made with Material for MkDocs_ notice to denote how
-the site was generated. The notice can be removed with the following setting
+the site was generated. The notice can be removed with the following option
 via `mkdocs.yml`:
 
 ``` yaml