Skip to content

Commit 3e46693

Browse files
squidfunksquidfunk
committed
Updated documentation for new privacy plugin settings
1 parent a7aa552 commit 3e46693

File tree

1 file changed

+95
-42
lines changed

1 file changed

+95
-42
lines changed

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

+95-42
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ template: overrides/main.html
44

55
# Ensuring data privacy
66

7-
Material for MkDocs makes compliance with data privacy regulations a breeze,
7+
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
1010
automatically bundled as part of the build process.
@@ -21,36 +21,55 @@ automatically bundled as part of the build process.
2121
:octicons-cpu-24: Plugin ·
2222
:octicons-beaker-24: Experimental
2323

24-
The built-in privacy plugin automatically downloads [external assets] as part of
25-
the build process and stores them alongside your documentation. Add the
26-
following lines to `mkdocs.yml`:
27-
24+
The built-in privacy plugin automatically identifies [external assets] as part
25+
of the build process and allows to download and serve them as part of your site.
26+
Add the following to `mkdocs.yml`:
2827

2928
``` yaml
3029
plugins:
3130
- privacy # (1)!
3231
```
3332
3433
1. Note that the privacy plugin should be located at the end of the list of
35-
`plugins`, as it will scan the resulting HTML for links to download and
34+
`plugins`, as it will scan the resulting HTML for resources to download and
3635
replace. If a plugin after the privacy plugin adds further
3736
[external assets], these assets will not be downloaded.
3837

3938
The following configuration options are available:
4039

41-
`download`{ #download }
40+
`enabled`{ #enabled }
4241

4342
: :octicons-milestone-24: Default: `true` – This option specifies whether
44-
the plugin should download [external assets]. If you want to switch the
45-
plugin off, e.g. for local builds, use an [environment variable]:
43+
the plugin is enabled when building your project. If you want to switch
44+
the plugin off, e.g. for local builds, use an [environment variable]:
45+
46+
``` yaml
47+
plugins:
48+
- privacy:
49+
enabled: !ENV [PRIVACY, false]
50+
```
51+
52+
`externals`{ #externals }
53+
54+
: :octicons-milestone-24: Default: `bundle` – This option specifies what the
55+
plugin should do when encountering external assets. There are two options:
56+
while `report` will issue a warning message during the build, `bundle` will
57+
automatically download all external files and adjust all references:
4658

4759
``` yaml
4860
plugins:
4961
- privacy:
50-
download: !ENV [DOWNLOAD, false]
62+
externals: bundle
5163
```
5264

53-
`download_directory`{ #download-directory }
65+
If you've removed all external assets from your project via [customization],
66+
it's still a good idea to enable the plugin and set the mode to `report`,
67+
as the plugin will make sure that there are no hidden external links in any
68+
Markdown files that were unintentionally added to the build.
69+
70+
[customization]: ../customization.md
71+
72+
`externals_directory`{ #externals-directory }
5473

5574
: :octicons-milestone-24: Default: `assets/externals` – This option
5675
specifies where the downloaded [external assets] will be stored. It's
@@ -59,7 +78,7 @@ The following configuration options are available:
5978
``` yaml
6079
plugins:
6180
- privacy:
62-
download_directory: assets/externals
81+
externals_directory: assets/externals
6382
```
6483

6584
[external assets]: #how-it-works
@@ -72,7 +91,7 @@ The following configuration options are available:
7291
different fonts that can be used to render your documentation. Most of the
7392
fonts include several weights and are split up into different character sets
7493
to keep the download size small, so the browser only downloads what is
75-
really needed. For Roboto, our default [regular font], this results in [28
94+
really needed. For Roboto, our default [regular font], this results in [42
7695
`*.woff2` files in total][example].
7796

7897
If Material for MkDocs would bundle all font files, the download size would
@@ -117,7 +136,7 @@ As a third measure, [`preconnect`][preconnect] hints used for DNS pre-fetching
117136
which might also leak the visitors IP address to a third party are automatically
118137
removed during the build process.
119138

120-
???+ example "Expand to inspect example"
139+
??? example "Expand to inspect example"
121140

122141
For the official documentation, the [built-in privacy] plugin downloads the
123142
following resources:
@@ -129,41 +148,61 @@ removed during the build process.
129148
├─ fonts.googleapis.com/css
130149
├─ fonts.gstatic.com/s/
131150
│ ├─ roboto/v29/
132-
│ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
133-
│ │ ├─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
134-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
135-
│ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
151+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
152+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
153+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
154+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
155+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
156+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
157+
│ │ ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
158+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
159+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
160+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
161+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
162+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
163+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
164+
│ │ ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
136165
│ │ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
137-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
166+
│ │ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
167+
│ │ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
168+
│ │ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
169+
│ │ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
138170
│ │ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
171+
│ │ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
172+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
173+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
174+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
175+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
176+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
177+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
178+
│ │ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
179+
│ │ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
139180
│ │ ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
140181
│ │ ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
141-
│ │ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
142-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
143182
│ │ ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
144-
│ │ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
145-
│ │ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
146-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
147183
│ │ ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
148-
│ │ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
149-
│ │ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
150-
│ │ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
151-
│ │ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
152-
│ │ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
153-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
154-
│ │ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
155-
│ │ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
156-
│ │ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
184+
│ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
157185
│ │ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
158-
│ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
159-
│ │ └─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
186+
│ │ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
187+
│ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
188+
│ │ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
189+
│ │ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
190+
│ │ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
191+
│ │ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
192+
│ │ └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
160193
│ └─ robotomono/v13/
161-
│ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_R-W4Ep0.woff2
162-
│ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_QOW4Ep0.woff2
163-
│ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_SuW4Ep0.woff2
164-
│ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_ROW4.woff2
165-
│ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_SeW4Ep0.woff2
166-
│ └─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_S-W4Ep0.woff2
194+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
195+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
196+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
197+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
198+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
199+
│ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
200+
│ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2
201+
│ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2
202+
│ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2
203+
│ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2
204+
│ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2
205+
│ └─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2
167206
└─ polyfill.io/v3/polyfill.min.js
168207
```
169208

@@ -210,6 +249,20 @@ carried out. You might want to:
210249

211250
Note that dynamically created URLs as part of scripts are not detected, and thus
212251
cannot be automatically downloaded. The [built-in privacy] plugin does not
213-
execute scripts – it can only detect complete URLs to download and replace.
252+
execute scripts – it can only detect fully qualified URLs to download and
253+
replace.
254+
255+
In short, don't do this:
256+
257+
``` js
258+
const cdn = "https://polyfill.io"
259+
const url = `${cdn}/v3/polyfill.min.js`
260+
```
261+
262+
Instead, always use fully qualified URLs:
263+
264+
``` js
265+
const url ="https://polyfill.io/v3/polyfill.min.js"
266+
```
214267

215268
[Insiders]: ../insiders/index.md

0 commit comments

Comments
 (0)