From 334efc3ce7ad041e45d69c2b91e87af2eb5e55a3 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 23 Mar 2022 11:08:22 +0100 Subject: [PATCH] Restructured documentation --- docs/blog/2021/the-past-present-and-future.md | 2 +- docs/insiders/index.md | 2 +- docs/schema/extra.json | 14 +- docs/setup/ensuring-data-privacy.md | 111 +++++++++++++++- docs/setup/setting-up-site-analytics.md | 124 ++---------------- 5 files changed, 126 insertions(+), 127 deletions(-) diff --git a/docs/blog/2021/the-past-present-and-future.md b/docs/blog/2021/the-past-present-and-future.md index a88e4d9ca..6935b0931 100644 --- a/docs/blog/2021/the-past-present-and-future.md +++ b/docs/blog/2021/the-past-present-and-future.md @@ -187,7 +187,7 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times. [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle [Content tabs: improved support]: ../../reference/content-tabs.md [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs - [Cookie consent]: ../../setup/setting-up-site-analytics.md#cookie-consent + [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read diff --git a/docs/insiders/index.md b/docs/insiders/index.md index e9710a6a6..ab1a96c04 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -218,7 +218,7 @@ are released for general availability. - [x] [Was this page helpful?] - [x] [Dismissable announcement bar] - [Cookie consent]: ../setup/setting-up-site-analytics.md#cookie-consent + [Cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent [Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful [Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read diff --git a/docs/schema/extra.json b/docs/schema/extra.json index aa6ab7810..4a64d159d 100644 --- a/docs/schema/extra.json +++ b/docs/schema/extra.json @@ -133,40 +133,40 @@ }, "consent": { "title": "Cookie consent", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "object", "properties": { "title": { "title": "Cookie consent title", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "string", "default": "Cookie consent" }, "description": { "title": "Cookie consent description", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "string" }, "cookies": { "title": "Cookies", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "object", "properties": { "analytics": { "title": "Cookie", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "oneOf": [ { "type": "object", "properties": { "name": { "title": "Cookie name", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "string" }, "checked": { "title": "Initial state", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", "type": "boolean", "default": true } diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 8bb3f4bcf..ed42fb720 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -7,13 +7,94 @@ template: overrides/main.html Material for MkDocs makes compliance with data privacy regulations very easy, as it offers a native [cookie consent] solution to seek explicit consent from users before setting up [tracking]. Additionally, external assets can be -automatically downloaded for self-hosting. +automatically downloaded for [self-hosting]. - [cookie consent]: setting-up-site-analytics.md#cookie-consent + [cookie consent]: #cookie-consent [tracking]: setting-up-site-analytics.md + [self-hosting]: #built-in-privacy-plugin ## Configuration +### Cookie consent + +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.10.0][Insiders] · +:octicons-milestone-24: Default: _none_ + +Material for MkDocs ships a native and extensible cookie consent form which +asks the user for his consent prior to sending any data via analytics. Add the +following to `mkdocs.yml`: + +``` yaml +extra: + consent: + title: Cookie consent + 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] can be +integrated by using the `cookies` field: + +=== "Custom cookie name" + + ``` yaml + extra: + consent: + cookies: + analytics: Custom name # (1)! + ``` + + 1. The default name of the `analytics` cookie is `Google Analytics`. + +=== "Custom initial state" + + ``` yaml + extra: + consent: + cookies: + analytics: + name: Google Analytics + checked: false + ``` + +=== "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: + +[![cookie consent enabled]][cookie consent enabled] + +In order to comply with GDPR, users must be able to change their cookie settings +at any time. This can be done by creating a simple link as part of any document, +e.g. your privacy policy: + +``` markdown +[Change cookie settings](#__consent){ .md-button } +``` + + [Insiders]: ../insiders/index.md + [custom cookies]: #custom-cookies + [cookie consent enabled]: ../assets/screenshots/consent.png + ### Built-in privacy plugin [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · @@ -299,4 +380,28 @@ Instead, always use fully qualified URLs: const url ="https://polyfill.io/v3/polyfill.min.js" ``` - [Insiders]: ../insiders/index.md +## Customization + +### Custom cookies + +If you've customized the [cookie consent] and added a `custom` cookie, the user +will be prompted to accept your custom cookie. Use [additional JavaScript] to +check whether the user accepted it: + +=== ":octicons-file-code-16: docs/javascripts/consent.js" + + ``` js + var consent = __md_get("__consent") + if (consent && consent.custom) { + /* The user accepted the cookie */ + } + ``` + +=== ":octicons-file-code-16: mkdocs.yml" + + ``` yaml + extra_javascript: + - javascripts/consent.js + ``` + + [additional JavaScript]: ../customization.md#additional-javascript diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index e299c13b0..faa55dda3 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -7,12 +7,11 @@ 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 -[cookie consent][extra.consent] and a [feedback widget] -[extra.analytics.feedback]. +[cookie consent] and a [feedback widget]. [Google Analytics]: https://developers.google.com/analytics - [extra.consent]: #cookie-consent - [extra.analytics.feedback]: #was-this-page-helpful + [cookie consent]: ensuring-data-privacy.md#cookie-consent + [feedback widget]: #was-this-page-helpful ## Configuration @@ -98,7 +97,7 @@ extra: using our feedback form. ``` -1. This feature is natively integrated with [Google Analytics][extra.analytics], +1. This feature is natively integrated with [Google Analytics][analytics], which is why `provider` and `property` are also required. However, it's also possible to provide a [custom feedback integration]. @@ -108,7 +107,7 @@ extra: 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]. +integrated with the [cookie consent] feature[^1]. [^1]: If the user doesn't accept the `analytics` cookie, the feedback widget is @@ -211,100 +210,20 @@ The following properties must be set for each rating: An alternative to GitHub issues is [Google Forms]. + [Insiders]: ../insiders/index.md [feedback widget]: #feedback - [extra.analytics]: #google-analytics + [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 } · -[:octicons-tag-24: insiders-2.10.0][Insiders] · -:octicons-milestone-24: Default: _none_ - -Material for MkDocs ships a native and extensible cookie consent form which -asks the user for his consent prior to sending any data via analytics. Add the -following to `mkdocs.yml`: - -``` yaml -extra: - consent: - title: Cookie consent - 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] can be -integrated by using the `cookies` field: - -=== "Custom cookie name" - - ``` yaml - extra: - consent: - cookies: - analytics: Custom name # (1)! - ``` - - 1. The default name of the `analytics` cookie is `Google Analytics`. - -=== "Custom initial state" - - ``` yaml - extra: - consent: - cookies: - analytics: - name: Google Analytics - checked: false - ``` - -=== "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: - -[![extra.consent enabled]][extra.consent enabled] - -In order to comply with GDPR, users must be able to change their cookie settings -at any time. This can be done by creating a simple link as part of any document, -e.g. your privacy policy: - -``` markdown -[Change cookie settings](#__consent){ .md-button } -``` - - [Insiders]: ../insiders/index.md - [custom cookies]: #custom-cookies - [extra.consent enabled]: ../assets/screenshots/consent.png - ## Usage ### Hiding the feedback widget -When [Metadata] is enabled, the [feedback widget][extra.analytics.feedback] can -be hidden for a document with custom front matter. Add the following lines at -the top of a Markdown file: +When [Metadata] is enabled, the [feedback widget] can be hidden for a document +with custom front matter. Add the following lines at the top of a Markdown file: ``` bash --- @@ -318,7 +237,6 @@ hide: [Metadata]: extensions/python-markdown.md#metadata - ## Customization ### Custom site analytics @@ -395,29 +313,5 @@ generated by users interacting with the feedback widget with the help of some - javascripts/feedback.js ``` -### Custom cookies - -If you've customized the [cookie consent][extra.consent] and added a `custom` -cookie, the user will be prompted to accept your custom cookie. Use [additional -JavaScript] to check whether the user accepted it: - -=== ":octicons-file-code-16: docs/javascripts/consent.js" - - ``` js - var consent = __md_get("__consent") - if (consent && consent.custom) { - /* The user accepted the cookie */ - } - ``` - -=== ":octicons-file-code-16: mkdocs.yml" - - ``` yaml - extra_javascript: - - javascripts/consent.js - ``` -   { #feedback style="margin: 0; height: 0" } - - [additional JavaScript]: ../customization.md#additional-javascript