Skip to content

Commit 334efc3

Browse files
squidfunksquidfunk
committed
Restructured documentation
1 parent c9cee0f commit 334efc3

File tree

5 files changed

+126
-127
lines changed

5 files changed

+126
-127
lines changed

‎docs/blog/2021/the-past-present-and-future.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
187187
[Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle
188188
[Content tabs: improved support]: ../../reference/content-tabs.md
189189
[Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs
190-
[Cookie consent]: ../../setup/setting-up-site-analytics.md#cookie-consent
190+
[Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent
191191
[Custom admonition icons]: ../../reference/admonitions.md#admonition-icons
192192
[Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
193193
[Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read

‎docs/insiders/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ are released for general availability.
218218
- [x] [Was this page helpful?]
219219
- [x] [Dismissable announcement bar]
220220

221-
[Cookie consent]: ../setup/setting-up-site-analytics.md#cookie-consent
221+
[Cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
222222
[Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful
223223
[Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read
224224

‎docs/schema/extra.json

+7-7
Original file line numberDiff line numberDiff line change
@@ -133,40 +133,40 @@
133133
},
134134
"consent": {
135135
"title": "Cookie consent",
136-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
136+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
137137
"type": "object",
138138
"properties": {
139139
"title": {
140140
"title": "Cookie consent title",
141-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
141+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
142142
"type": "string",
143143
"default": "Cookie consent"
144144
},
145145
"description": {
146146
"title": "Cookie consent description",
147-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
147+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
148148
"type": "string"
149149
},
150150
"cookies": {
151151
"title": "Cookies",
152-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
152+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
153153
"type": "object",
154154
"properties": {
155155
"analytics": {
156156
"title": "Cookie",
157-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
157+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
158158
"oneOf": [
159159
{
160160
"type": "object",
161161
"properties": {
162162
"name": {
163163
"title": "Cookie name",
164-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
164+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
165165
"type": "string"
166166
},
167167
"checked": {
168168
"title": "Initial state",
169-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#cookie-consent",
169+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
170170
"type": "boolean",
171171
"default": true
172172
}

‎docs/setup/ensuring-data-privacy.md

+108-3
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,94 @@ template: overrides/main.html
77
Material for MkDocs makes compliance with data privacy regulations very easy,
88
as it offers a native [cookie consent] solution to seek explicit consent from
99
users before setting up [tracking]. Additionally, external assets can be
10-
automatically downloaded for self-hosting.
10+
automatically downloaded for [self-hosting].
1111

12-
[cookie consent]: setting-up-site-analytics.md#cookie-consent
12+
[cookie consent]: #cookie-consent
1313
[tracking]: setting-up-site-analytics.md
14+
[self-hosting]: #built-in-privacy-plugin
1415

1516
## Configuration
1617

18+
### Cookie consent
19+
20+
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
21+
[:octicons-tag-24: insiders-2.10.0][Insiders] ·
22+
:octicons-milestone-24: Default: _none_
23+
24+
Material for MkDocs ships a native and extensible cookie consent form which
25+
asks the user for his consent prior to sending any data via analytics. Add the
26+
following to `mkdocs.yml`:
27+
28+
``` yaml
29+
extra:
30+
consent:
31+
title: Cookie consent
32+
description: >- # (1)!
33+
We use cookies to recognize your repeated visits and preferences, as well
34+
as to measure the effectiveness of our documentation and whether users
35+
find what they're searching for. With your consent, you're helping us to
36+
make our documentation better.
37+
```
38+
39+
1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
40+
terms of service or other parts of the site.
41+
42+
Note that both, `title` and `description`, are required. If Google Analytics
43+
was configured via `mkdocs.yml`, the cookie consent will automatically include
44+
a setting for the user to disable it. Furthermore, [custom cookies] can be
45+
integrated by using the `cookies` field:
46+
47+
=== "Custom cookie name"
48+
49+
``` yaml
50+
extra:
51+
consent:
52+
cookies:
53+
analytics: Custom name # (1)!
54+
```
55+
56+
1. The default name of the `analytics` cookie is `Google Analytics`.
57+
58+
=== "Custom initial state"
59+
60+
``` yaml
61+
extra:
62+
consent:
63+
cookies:
64+
analytics:
65+
name: Google Analytics
66+
checked: false
67+
```
68+
69+
=== "Custom cookie"
70+
71+
``` yaml
72+
extra:
73+
consent:
74+
cookies:
75+
analytics: Google Analytics # (1)!
76+
custom: Custom cookie
77+
```
78+
79+
1. If you add a custom cookie to the `cookies` field, the `analytics`
80+
cookie must be added back explicitly, or analytics won't be triggered.
81+
82+
When a user first visits your site, a cookie consent form is rendered:
83+
84+
[![cookie consent enabled]][cookie consent enabled]
85+
86+
In order to comply with GDPR, users must be able to change their cookie settings
87+
at any time. This can be done by creating a simple link as part of any document,
88+
e.g. your privacy policy:
89+
90+
``` markdown
91+
[Change cookie settings](#__consent){ .md-button }
92+
```
93+
94+
[Insiders]: ../insiders/index.md
95+
[custom cookies]: #custom-cookies
96+
[cookie consent enabled]: ../assets/screenshots/consent.png
97+
1798
### Built-in privacy plugin
1899

19100
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
@@ -299,4 +380,28 @@ Instead, always use fully qualified URLs:
299380
const url ="https://polyfill.io/v3/polyfill.min.js"
300381
```
301382

302-
[Insiders]: ../insiders/index.md
383+
## Customization
384+
385+
### Custom cookies
386+
387+
If you've customized the [cookie consent] and added a `custom` cookie, the user
388+
will be prompted to accept your custom cookie. Use [additional JavaScript] to
389+
check whether the user accepted it:
390+
391+
=== ":octicons-file-code-16: docs/javascripts/consent.js"
392+
393+
``` js
394+
var consent = __md_get("__consent")
395+
if (consent && consent.custom) {
396+
/* The user accepted the cookie */
397+
}
398+
```
399+
400+
=== ":octicons-file-code-16: mkdocs.yml"
401+
402+
``` yaml
403+
extra_javascript:
404+
- javascripts/consent.js
405+
```
406+
407+
[additional JavaScript]: ../customization.md#additional-javascript

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

+9-115
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,11 @@ template: overrides/main.html
77
As with any other service offered on the web, understanding how your project
88
documentation is actually used can be an essential success factor. Material for
99
MkDocs natively integrates with [Google Analytics] and offers a customizable
10-
[cookie consent][extra.consent] and a [feedback widget]
11-
[extra.analytics.feedback].
10+
[cookie consent] and a [feedback widget].
1211

1312
[Google Analytics]: https://developers.google.com/analytics
14-
[extra.consent]: #cookie-consent
15-
[extra.analytics.feedback]: #was-this-page-helpful
13+
[cookie consent]: ensuring-data-privacy.md#cookie-consent
14+
[feedback widget]: #was-this-page-helpful
1615

1716
## Configuration
1817

@@ -98,7 +97,7 @@ extra:
9897
using our <a href="..." target=_blank>feedback form</a>.
9998
```
10099
101-
1. This feature is natively integrated with [Google Analytics][extra.analytics],
100+
1. This feature is natively integrated with [Google Analytics][analytics],
102101
which is why `provider` and `property` are also required. However, it's also
103102
possible to provide a [custom feedback integration].
104103

@@ -108,7 +107,7 @@ extra:
108107
Both properties, `title` and `ratings`, are required. Note that it's allowed to
109108
define more than two ratings, e.g. to implement a 1-5 star rating. Since the
110109
feedback widget sends data to a third-party service, it is, of course, natively
111-
integrated with the [cookie consent][extra.consent] feature[^1].
110+
integrated with the [cookie consent] feature[^1].
112111

113112
[^1]:
114113
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:
211210

212211
An alternative to GitHub issues is [Google Forms].
213212

213+
[Insiders]: ../insiders/index.md
214214
[feedback widget]: #feedback
215-
[extra.analytics]: #google-analytics
215+
[analytics]: #google-analytics
216216
[feedback report]: ../assets/screenshots/feedback-report.png
217217
[custom feedback integration]: #custom-site-feedback
218218
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
219219
[Google Forms]: https://www.google.com/forms/about/
220220

221-
### Cookie consent
222-
223-
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
224-
[:octicons-tag-24: insiders-2.10.0][Insiders] ·
225-
:octicons-milestone-24: Default: _none_
226-
227-
Material for MkDocs ships a native and extensible cookie consent form which
228-
asks the user for his consent prior to sending any data via analytics. Add the
229-
following to `mkdocs.yml`:
230-
231-
``` yaml
232-
extra:
233-
consent:
234-
title: Cookie consent
235-
description: >- # (1)!
236-
We use cookies to recognize your repeated visits and preferences, as well
237-
as to measure the effectiveness of our documentation and whether users
238-
find what they're searching for. With your consent, you're helping us to
239-
make our documentation better.
240-
```
241-
242-
1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
243-
terms of service or other parts of the site.
244-
245-
Note that both, `title` and `description`, are required. If Google Analytics
246-
was configured via `mkdocs.yml`, the cookie consent will automatically include
247-
a setting for the user to disable it. Furthermore, [custom cookies] can be
248-
integrated by using the `cookies` field:
249-
250-
=== "Custom cookie name"
251-
252-
``` yaml
253-
extra:
254-
consent:
255-
cookies:
256-
analytics: Custom name # (1)!
257-
```
258-
259-
1. The default name of the `analytics` cookie is `Google Analytics`.
260-
261-
=== "Custom initial state"
262-
263-
``` yaml
264-
extra:
265-
consent:
266-
cookies:
267-
analytics:
268-
name: Google Analytics
269-
checked: false
270-
```
271-
272-
=== "Custom cookie"
273-
274-
``` yaml
275-
extra:
276-
consent:
277-
cookies:
278-
analytics: Google Analytics # (1)!
279-
custom: Custom cookie
280-
```
281-
282-
1. If you add a custom cookie to the `cookies` field, the `analytics`
283-
cookie must be added back explicitly, or analytics won't be triggered.
284-
285-
When a user first visits your site, a cookie consent form is rendered:
286-
287-
[![extra.consent enabled]][extra.consent enabled]
288-
289-
In order to comply with GDPR, users must be able to change their cookie settings
290-
at any time. This can be done by creating a simple link as part of any document,
291-
e.g. your privacy policy:
292-
293-
``` markdown
294-
[Change cookie settings](#__consent){ .md-button }
295-
```
296-
297-
[Insiders]: ../insiders/index.md
298-
[custom cookies]: #custom-cookies
299-
[extra.consent enabled]: ../assets/screenshots/consent.png
300-
301221
## Usage
302222

303223
### Hiding the feedback widget
304224

305-
When [Metadata] is enabled, the [feedback widget][extra.analytics.feedback] can
306-
be hidden for a document with custom front matter. Add the following lines at
307-
the top of a Markdown file:
225+
When [Metadata] is enabled, the [feedback widget] can be hidden for a document
226+
with custom front matter. Add the following lines at the top of a Markdown file:
308227

309228
``` bash
310229
---
@@ -318,7 +237,6 @@ hide:
318237

319238
[Metadata]: extensions/python-markdown.md#metadata
320239

321-
322240
## Customization
323241

324242
### Custom site analytics
@@ -395,29 +313,5 @@ generated by users interacting with the feedback widget with the help of some
395313
- javascripts/feedback.js
396314
```
397315

398-
### Custom cookies
399-
400-
If you've customized the [cookie consent][extra.consent] and added a `custom`
401-
cookie, the user will be prompted to accept your custom cookie. Use [additional
402-
JavaScript] to check whether the user accepted it:
403-
404-
=== ":octicons-file-code-16: docs/javascripts/consent.js"
405-
406-
``` js
407-
var consent = __md_get("__consent")
408-
if (consent && consent.custom) {
409-
/* The user accepted the cookie */
410-
}
411-
```
412-
413-
=== ":octicons-file-code-16: mkdocs.yml"
414-
415-
``` yaml
416-
extra_javascript:
417-
- javascripts/consent.js
418-
```
419-
420316
&nbsp;
421317
{ #feedback style="margin: 0; height: 0" }
422-
423-
[additional JavaScript]: ../customization.md#additional-javascript

0 commit comments

Comments
 (0)