From 3e466930924752cb2e71654341512e3d7be473a2 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 27 Feb 2022 13:04:34 +0100 Subject: [PATCH] Updated documentation for new privacy plugin settings --- docs/setup/ensuring-data-privacy.md | 137 +++++++++++++++++++--------- 1 file changed, 95 insertions(+), 42 deletions(-) diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index bc0765438..e6957b65f 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -4,7 +4,7 @@ template: overrides/main.html # Ensuring data privacy -Material for MkDocs makes compliance with data privacy regulations a breeze, +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 bundled as part of the build process. @@ -21,10 +21,9 @@ automatically bundled as part of the build process. :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental -The built-in privacy plugin automatically downloads [external assets] as part of -the build process and stores them alongside your documentation. Add the -following lines to `mkdocs.yml`: - +The built-in privacy plugin automatically identifies [external assets] as part +of the build process and allows to download and serve them as part of your site. +Add the following to `mkdocs.yml`: ``` yaml plugins: @@ -32,25 +31,45 @@ plugins: ``` 1. Note that the privacy plugin should be located at the end of the list of - `plugins`, as it will scan the resulting HTML for links to download and + `plugins`, as it will scan the resulting HTML for resources to download and replace. If a plugin after the privacy plugin adds further [external assets], these assets will not be downloaded. The following configuration options are available: -`download`{ #download } +`enabled`{ #enabled } : :octicons-milestone-24: Default: `true` – This option specifies whether - the plugin should download [external assets]. If you want to switch the - plugin off, e.g. for local builds, use an [environment variable]: + the plugin is enabled when building your project. If you want to switch + the plugin off, e.g. for local builds, use an [environment variable]: ``` yaml plugins: - privacy: - download: !ENV [DOWNLOAD, false] + enabled: !ENV [PRIVACY, false] ``` -`download_directory`{ #download-directory } +`externals`{ #externals } + +: :octicons-milestone-24: Default: `bundle` – This option specifies what the + plugin should do when encountering external assets. There are two options: + while `report` will issue a warning message during the build, `bundle` will + automatically download all external files and adjust all references: + + ``` yaml + plugins: + - privacy: + externals: bundle + ``` + + If you've removed all external assets from your project via [customization], + it's still a good idea to enable the plugin and set the mode to `report`, + as the plugin will make sure that there are no hidden external links in any + Markdown files that were unintentionally added to the build. + + [customization]: ../customization.md + +`externals_directory`{ #externals-directory } : :octicons-milestone-24: Default: `assets/externals` – This option specifies where the downloaded [external assets] will be stored. It's @@ -59,7 +78,7 @@ The following configuration options are available: ``` yaml plugins: - privacy: - download_directory: assets/externals + externals_directory: assets/externals ``` [external assets]: #how-it-works @@ -72,7 +91,7 @@ The following configuration options are available: different fonts that can be used to render your documentation. Most of the fonts include several weights and are split up into different character sets to keep the download size small, so the browser only downloads what is - really needed. For Roboto, our default [regular font], this results in [28 + really needed. For Roboto, our default [regular font], this results in [42 `*.woff2` files in total][example]. 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 which might also leak the visitors IP address to a third party are automatically removed during the build process. -???+ example "Expand to inspect example" +??? example "Expand to inspect example" For the official documentation, the [built-in privacy] plugin downloads the following resources: @@ -129,41 +148,61 @@ removed during the build process. ├─ fonts.googleapis.com/css ├─ fonts.gstatic.com/s/ │ ├─ roboto/v29/ - │ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2 + │ │ ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2 │ │ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2 │ │ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2 │ │ ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2 │ │ ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2 - │ │ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2 │ │ ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2 - │ │ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2 │ │ ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2 - │ │ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2 - │ │ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2 - │ │ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2 - │ │ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2 │ │ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2 - │ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2 - │ │ └─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2 + │ │ └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2 │ └─ robotomono/v13/ - │ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_R-W4Ep0.woff2 - │ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_QOW4Ep0.woff2 - │ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_SuW4Ep0.woff2 - │ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_ROW4.woff2 - │ ├─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_SeW4Ep0.woff2 - │ └─ L0xuDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vq_S-W4Ep0.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2 + │ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2 + │ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2 + │ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2 + │ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2 + │ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2 + │ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2 + │ └─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2 └─ polyfill.io/v3/polyfill.min.js ``` @@ -210,6 +249,20 @@ carried out. You might want to: Note that dynamically created URLs as part of scripts are not detected, and thus cannot be automatically downloaded. The [built-in privacy] plugin does not -execute scripts – it can only detect complete URLs to download and replace. +execute scripts – it can only detect fully qualified URLs to download and +replace. + +In short, don't do this: + +``` js +const cdn = "https://polyfill.io" +const url = `${cdn}/v3/polyfill.min.js` +``` + +Instead, always use fully qualified URLs: + +``` js +const url ="https://polyfill.io/v3/polyfill.min.js" +``` [Insiders]: ../insiders/index.md