Updated cookie consent documentation

Author: squidfunk

Diff for: docs/setup/setting-up-site-analytics.md

@@ -5,12 +5,12 @@ template: overrides/main.html
 # Setting up site analytics
 
 As with any other service offered on the web, understanding how your project
-documentation is actually used can be an essential success factor. While
-Material for MkDocs natively integrates with [Google Analytics][1], [other
-analytics providers][2] can be used, too.
+documentation is actually used can be an essential success factor. Material for
+MkDocs natively integrates with [Google Analytics][1] and offers a customizable
+and extendable [cookie consent][2].
 
   [1]: https://developers.google.com/analytics
-  [2]: #other-analytics-providers
+  [2]: #cookie-consent
 
 ## Configuration
 
@@ -63,69 +63,122 @@ yourself, [this tutorial][4] might be a good start._
 ### Cookie consent
 
 [:octicons-file-code-24: Source][5] ·
-:octicons-beaker-24: Experimental ·
+:octicons-milestone-24: Default: _none_ ·
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
 
 Material for MkDocs ships a native and extensible cookie consent form, which
-when enabled will ask the user for his consent prior to sending analytics.
-Add the following to `mkdocs.yml`:
+asks the user for his consent prior to setting up analytics. Add the following
+to `mkdocs.yml`:
 
 ``` yaml
 extra:
   consent:
     title: Cookie consent
-    description: >
+    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
       make our documentation better.
 ```
 
+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
+configured via `mkdocs.yml`, the cookie consent will automatically include a
+setting for the user to disable it. Furthermore, [custom cookies][6] can be
+integrated by using the `cookies` field:
+
+===  "Change cookie name"
+
+    ``` yaml
+    extra:
+      consent:
+        cookies:
+          analytics: Custom name # (1)
+    ```
+
+    1. The default name of the `analytics` cookie is `Google Analytics`.
+
+===  "Add custom cookie"
+
+    ``` yaml
+    extra:
+      consent:
+        cookies:
+          analytics: Google Analytics # (1)
+          custom: Custom cookie
+    ```
+
+    1. If you add a custom cookie to the `cookies` field, the `analytics` cookie 
+       must be added back explicitly, or analytics won't be triggered.
+
 When a user first visits your site, a cookie consent form is rendered:
 
-[![With tabs][6]][6]
+[![With tabs][7]][7]
 
   [5]: ../insiders/index.md
-  [6]: ../assets/screenshots/consent.png
-
-_Let's get this feature out of the experimental status! You are encouraged to
-share your feedback in #1914, so we can provide the necessary configuration
-options for easy customizations. If you wish to customize it today, you can
-override_ `partials/consent.html`.
+  [6]: #custom-cookies
+  [7]: ../assets/screenshots/consent.png
 
 ## Customization
 
-### Other analytics providers
+### Custom site analytics
 
 [:octicons-file-code-24: Source][3] ·
-:octicons-mortar-board-24: Difficulty: _easy_
+:octicons-mortar-board-24: Difficulty: _moderate_
 
-In order to integrate another analytics service provider offering an
-asynchronous JavaScript-based tracking solution, you can [extend the theme][7]
-and [override the `analytics` block][8]:
+In order to integrate another analytics service provider offering a 
+JavaScript-based tracking solution, you can [extend the theme][8] and add a new 
+`custom.html` partial [here][9]. The name of the partial can then be used to 
+configure the custom integration from `mkdocs.yml`:
 
-``` html
-{% block analytics %}
-  <!-- Add custom analytics integration here -->
-{% endblock %}
+``` yaml
+extra:
+  analytics:
+    provider: custom # (1)
+    key: value # (2)
 ```
 
-  [7]: ../customization.md#extending-the-theme
-  [8]: ../customization.md#overriding-blocks-recommended
+1. Of course, you can change the name to the partial to anything you like.
+2. You can add arbitrary `key` and `value` combinations to configure your custom
+   integration. This is especially useful if you're sharing the custom
+   integration across multiple repositories.
+
+  [8]: ../customization.md#extending-the-theme
+  [9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics
 
-If you're using [instant loading][9], you may use the `location$` observable,
+#### Instant loading
+
+If you're using [instant loading][10], you may use the `location$` observable,
 which will emit the current `URL` to listen for navigation events and register
 a page view event with:
 
 ``` js
 location$.subscribe(function(url) {
-  /* Add custom page event tracking here */
+  /* Track a page event */
 })
 ```
 
-Note that this must be integrated with [additional JavaScript][10], and cannot be
-included as part of the `analytics` block, as it is included in the `head` of
-the document.
+Note that this must be integrated with [additional JavaScript][11].
+
+  [10]: setting-up-navigation.md#instant-loading
+  [11]: ../customization.md#additional-javascript
+
+### Custom cookies
+
+[:octicons-file-code-24: Source][3] ·
+:octicons-mortar-board-24: Difficulty: _moderate_
+
+If you've customized the [cookie consent][12] and added a `custom` cookie, the
+user will be prompted to accept your custom cookie. Use
+[additional JavaScript][11] to check whether the user accepted it:
+
+``` js
+var consent = __md_get("__consent")
+if (consent && consent.custom) {
+  /* The user accepted the cookie */
+}
+```
 
-  [9]: setting-up-navigation.md#instant-loading
-  [10]: ../customization.md#additional-javascript
+  [12]: #cookie-consent