From 227d61026fc1e2447e59fa0af56a94ee1a6e16aa Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 20 Feb 2022 19:49:23 +0100 Subject: [PATCH] Added documentation for privacy plugin --- CHANGELOG | 4 + docs/creating-your-site.md | 2 + docs/insiders/changelog.md | 4 + docs/insiders/index.md | 10 +- docs/setup/changing-the-fonts.md | 7 + docs/setup/ensuring-data-privacy.md | 193 ++++++++++++++++++++++++++ docs/setup/setting-up-social-cards.md | 2 +- mkdocs.yml | 1 + 8 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 docs/setup/ensuring-data-privacy.md diff --git a/CHANGELOG b/CHANGELOG index 90cdc1869..8f9b0a570 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-8.2.1+insiders-4.9.0 (2022-02-20) + + * Added privacy plugin: automatic downloading of external assets + mkdocs-material-8.2.1 (2022-02-17) * Fixed module 'material.plugins' not being found (8.2.0 regression) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 74f613918..01bbe6fcf 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -148,6 +148,7 @@ and much more: - [Changing the fonts] - [Changing the language] - [Changing the logo and icons] +- [Ensuring data privacy] - [Setting up navigation] - [Setting up site search] - [Setting up site analytics] @@ -169,6 +170,7 @@ technical writing experience. [Changing the fonts]: setup/changing-the-fonts.md [Changing the language]: setup/changing-the-language.md [Changing the logo and icons]: setup/changing-the-logo-and-icons.md + [Ensuring data privacy]: setup/ensuring-data-privacy.md [Setting up navigation]: setup/setting-up-navigation.md [Setting up site search]: setup/setting-up-site-search.md [Setting up site analytics]: setup/setting-up-site-analytics.md diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 40fd1349c..5bb574c8b 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 4.9.0 _ February 20, 2022 { id="4.9.0" } + +- Added privacy plugin: automatic downloading of external assets + ### 4.8.3 _ February 13, 2022 { id="4.8.3" } - Fixed #3560: Mermaid diagrams don't render for `file://` locations diff --git a/docs/insiders/index.md b/docs/insiders/index.md index e6cf1169c..9b88cd1af 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -166,8 +166,9 @@ The following features are solely available via Material for MkDocs Insiders:
+- [x] [Privacy plugin] :material-new-box: - [x] [Table of contents anchor following] :material-new-box: -- [x] [Offline search] :material-new-box: +- [x] [Offline search] - [x] [Annotations] - [x] [Navigation icons] - [x] [Code annotations: anchor links] @@ -258,6 +259,13 @@ are released for general availability. [Annotations]: ../reference/annotations.md [Navigation icons]: ../reference/index.md#setting-the-page-icon +#### $ 14,000 – Goat's Horn + +- [x] [Privacy plugin] +- [ ] and much more, to be announced ... + + [Privacy plugin]: ../setup/ensuring-data-privacy.md + ### Goals completed This section lists all funding goals that were previously completed, which means diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index ea3f4f06c..d67825f6a 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -66,8 +66,15 @@ theme: font: false ``` +!!! tip "Automatically bundle Google Fonts" + + The brand-new [built-in privacy] plugin makes it easy to use Google Fonts + while complying with the __General Data Protection Regulation__ (GDPR), + by automatically downloading and self-hosting the web font files. + [data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users [font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [built-in privacy]: ensuring-data-privacy.md#built-in-privacy ## Customization diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md new file mode 100644 index 000000000..fae72e479 --- /dev/null +++ b/docs/setup/ensuring-data-privacy.md @@ -0,0 +1,193 @@ +--- +template: overrides/main.html +--- + +# Ensuring data privacy + +Material for MkDocs makes compliance with data privacy regulations a breeze, +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. + + [cookie consent]: setting-up-site-analytics.md#cookie-consent + [tracking]: setting-up-site-analytics.md + +## Configuration + +### Built-in privacy + +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.9.0][Insiders] · +: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`: + + +``` yaml +plugins: + - privacy # (1)! +``` + +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 + replace. If a plugin owing the privacy plugin adds further + [external assets], these assets will not be downloaded. + +The following configuration options are available: + +`download`{ #download } + +: :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]: + + ``` yaml + plugins: + - privacy: + download: !ENV [DOWNLOAD, false] + ``` + +`download_directory`{ #download-directory } + +: :octicons-milestone-24: Default: `assets/externals` – This option + specifies where the downloaded [external assets] will be stored. It's + normally not necessary to change this option: + + ``` yaml + plugins: + - privacy: + download_directory: assets/externals + ``` + + [external assets]: #how-it-works + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables + +#### How it works + +The [built-in privacy] plugin scans the resulting HTML for links to external +resources, including external scripts, style sheets, images and web fonts, and +downloads them to bundle them with your documentation site. Every URL refering +to an external resource, no matter if part of a template or Markdown file is +then replaced with the URL to the local copy. Example: + +``` html + +``` + +The external script is downloaded, and the link is replaced with: + +``` html + +``` + +Style sheets are scanned for external `url(...)` references, e.g. images and +web fonts, which are then also downloaded and bundled with your documentation +site. This means that [Google Fonts] can be configured in `mkdocs.yml` as usual, +as the [built-in privacy] plugin automatically downloads and bundles all +dependent resources. + +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" + + For the official documentation, the [built-in privacy] plugin downloads the + following resources: + + ``` sh + . + └─ assets/externals/ + ├─ cdnjs.cloudflare.com/ajax/tablesort/5.2.1/tablesort.min.js + ├─ fonts.googleapis.com/css + ├─ fonts.gstatic.com/s/ + │ ├─ roboto/v29/ + │ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2 + │ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2 + │ │ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.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 + │ │ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2 + │ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2 + │ │ └─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.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 + └─ polyfill.io/v3/polyfill.min.js + ``` + + [built-in privacy]: #built-in-privacy + [Google Fonts]: changing-the-fonts.md + [preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch + +#### Caching recommended { #caching data-toc-label="Caching" } + +All downloaded files are written to the `.cache` directory, significantly +reducing the duration of subsequent builds as only replacements need to be +carried out. You might want to: + +1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`. +2. When building your site for publishing, use a build cache to save the + `.cache` directory in between builds. Taking the example from the + [publishing guide], add the following lines: + + ``` yaml hl_lines="15-18" + name: ci + on: + push: + branches: + - master + - main + jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: 3.x + - uses: actions/cache@v2 + with: + key: ${{ github.ref }} + path: .cache + - run: pip install mkdocs-material + - run: mkdocs gh-deploy --force + ``` + + [publishing guide]: ../publishing-your-site.md#with-github-actions + +#### Limitations + +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. +This is why (currently) nested resources from `*.js` files are not processed. + + [Insiders]: ../insiders/index.md diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index 22acd0ac3..0d5cebfc8 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -64,7 +64,7 @@ The following configuration options are available: ``` yaml plugins: - social: - cards: !ENV [SOCIAL_CARDS, false] + cards: !ENV [CARDS, false] ``` `cards_color`{ #cards-color } diff --git a/mkdocs.yml b/mkdocs.yml index 83757f5da..400dab38d 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -176,6 +176,7 @@ nav: - Changing the fonts: setup/changing-the-fonts.md - Changing the language: setup/changing-the-language.md - Changing the logo and icons: setup/changing-the-logo-and-icons.md + - Ensuring data privacy: setup/ensuring-data-privacy.md - Setting up navigation: setup/setting-up-navigation.md - Setting up site search: setup/setting-up-site-search.md - Setting up site analytics: setup/setting-up-site-analytics.md