mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-26 22:34:15 +01:00

2024-10-09 10:09:44 +02:00

13 KiB

Raw Blame History

title	icon
Built-in privacy plugin	material/shield-account

Built-in privacy plugin

The privacy plugin offers a streamlined solution for automatically self-hosting external assets. With just a single line of configuration, the plugin can automatically identify and download external assets, making GDPR compliance as effortless as it can possibly be.

Objective

How it works

The plugin scans the generated HTML for external assets, i.e., scripts, style sheets, images, and web fonts, downloads them, stores them in the [site directory][mkdocs.site_dir] and replaces all references with links to the downloaded copies for effortless self-hosting. For example:

<script src="https://example.com/script.js"></script>

This external script is downloaded, and the link is replaced with:

<script src="assets/external/example.com/script.js"></script>

Of course, scripts and style sheets can reference further external assets, which is why this process is repeated recursively until no further external assets are detected:

Scripts are scanned for further scripts, style sheets and JSON files
Style sheets are scanned for images and web fonts

Additionally, hints like preconnect, used to reduce latency when requesting external assets, are removed from the output, as they're not necessary when self-hosting. After the plugin has done it's work, your project will be free of requests to external services.

There are some limitations.

When to use it

The plugin was developed to make compliance with the 2018 European General Data Protection Regulation (GDPR) as simple as possible, while retaining the flexibility and power that Material for MkDocs offers, like for example its tight integration with Google Fonts.

But, that's only the start. For example, if your project includes a lot of images, enabling the plugin allows to move them outside of your repository, as the plugin will automatically download and store them in the [site directory] [mkdocs.site_dir] when building your project.

Even more interestingly, the plugin can be combined with other built-in plugins that Material for MkDocs offers, in order to create sophisticated build pipelines tailored to your project:

:material-rabbit: Built-in optimize plugin

The optimize plugin allows to optimize all downloaded external assets detected by the privacy plugin by using compression and conversion techniques.

External media files are automatically downloaded and optimized
:material-connection: Built-in offline plugin

The offline plugin adds support for building offline-capable documentation, so you can distribute the [site directory][mkdocs.site_dir] as a .zip file that can be downloaded.

Your documentation can work without connectivity to the internet

Configuration

As with all built-in plugins, getting started with the privacy plugin is straightforward. Just add the following lines to mkdocs.yml, and start effortlessly self-hosting external assets:

plugins:
  - privacy

The privacy plugin is built into Material for MkDocs and doesn't need to be installed.

General

The following settings are available:

Use this setting to enable or disable the plugin when building your project. If you want to disable the plugin, e.g., for local builds, you can use an [environment variable][mkdocs.env] in mkdocs.yml:

plugins:
  - privacy:
      enabled: !ENV [CI, false]

This configuration enables the plugin only during continuous integration (CI).

With more CPUs available, the plugin can do more work in parallel, and thus complete handling of external assets faster. If you want to disable concurrent processing completely, use:

plugins:
  - privacy:
      concurrency: 1

By default, the plugin uses all available CPUs - 1 with a minimum of 1.

Caching

The plugin implements an intelligent caching mechanism, ensuring that external assets are only downloaded when they're not already contained in the cache. While the initial build might take some time, it's a good idea to use caching, as it will speed up consecutive builds.

The following settings are available for caching:

Use this setting to instruct the plugin to bypass the cache, in order to re-schedule downloads for all external assets, even though the cache may not be stale. It's normally not necessary to specify this setting, except for when debugging the plugin itself. Caching can be disabled with:

plugins:
  - privacy:
      cache: false

It is normally not necessary to specify this setting, except for when you want to change the path within your root directory where downloaded copies are cached. If you want to change it, use:

plugins:
  - privacy:
      cache_dir: my/custom/dir

If you're using multiple instances of the plugin, it can be a good idea to set different cache directories for both instances, so that they don't interfere with each other.

Logging

The following settings are available for logging:

Use this setting to control whether the plugin should display log messages when building your site. While not being recommended, you can disable logging with:

plugins:
  - privacy:
      log: false

Use this setting to control the log level that the plugin should employ when encountering errors, which requires that the [log][config.log] setting is enabled. The following log levels are available:

=== "error"

``` yaml
plugins:
  - privacy:
      log_level: error
```

Only errors are reported.

=== "warn"

``` yaml
plugins:
  - privacy:
      log_level: warn
```

Errors and warnings are reported, terminating the build in
[`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot
be created due to a lack of permissions on Windows systems (#6550).

=== "info"

``` yaml
plugins:
  - privacy:
      log_level: info
```

Errors, warnings and informational messages are reported, including which
assets were successfully downloaded by the plugin.

=== "debug"

``` yaml
plugins:
  - privacy:
      log_level: debug
```

All messages are reported, including debug messages, if and only if MkDocs
was started with the `--verbose` flag. Note that this will print a lot of
messages and is only useful for debugging.

External assets

The following settings are available for external assets:

Use this setting to control whether the plugin should download external assets. If you only want the plugin to process external links, you can disable handling of external assets with:

plugins:
  - privacy:
      assets: false

Use this setting to control whether the plugin should downloads or only report external assets when they're encountered. If you already self-host all external assets, this setting can be used as a safety net to detect links to external assets placed by the author in pages:

plugins:
  - privacy:
      assets_fetch: true

It is normally not necessary to specify this setting, except for when you want to change the path within the [site directory][mkdocs.site_dir] where external assets are stored. If you want to change it, use:

plugins:
  - privacy:
      assets_fetch_dir: my/custom/dir

This configuration stores the downloaded copies at my/custom/dir in the [site directory][mkdocs.site_dir].

Use this setting to enable downloading of external assets for specific origins, e.g., when using multiple instances of the plugin to fine-tune processing of external assets for different origins:

plugins:
  - privacy:
      assets_include:
        - unsplash.com/*

Use this setting to disable downloading of external assets for specific origins, e.g., when using multiple instances of the plugin to fine-tune processing of external assets for different origins:

plugins:
  - privacy:
      assets_exclude: # (1)!
        - unpkg.com/mathjax@3/*
        - giscus.app/*

MathJax loads web fonts for typesetting of mathematical content through relative URLs, and thus cannot be automatically bundled by the privacy plugin. MathJax can be self-hosted.

Giscus, which we recommend to use as a comment system, uses a technique called code-splitting to load only the code that is necessary, which is implemented via relative URLs. Giscus can be self-hosted as well.

External links

The following settings are available for external links:

Use this setting to instruct the plugin to parse and process external links to annotate them for improved security, or to automatically add additional attributes to external links. If you want to disable processing of external links, use:

plugins:
  - privacy:
      links: false

Use this setting to specify additional attributes that should be added to external links, for example, to add target="_blank" to all external links so they open in a new tab:

plugins:
  - privacy:
      links_attr_map:
        target: _blank

It is normally not recommended to change this setting, as it will automatically annotate external links that open in a new window with rel="noopener" for improved security:

plugins:
  - privacy:
      links_noopener: true

Limitations

Dynamic URLs

Dynamically created URLs as part of scripts are not detected, and thus cannot be downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:

const host = "https://example.com"
const path = `${host}/script.js`

Instead, always use fully qualified URLs:

const url ="https://example.com/script.js"

Embedded HTML

By default, embedded HTML files (e.g. in iframes) are not scanned for external assets. This is a limitation of MkDocs, as it considers .html files to be templates, which must be explicitly listed under [extra_templates][mkdocs.extra_templates]. Thus, to self-host external assets of an embedded HTML file:

extra_templates:
  - iframe.html

Note that the path to iframe.html is relative to the [docs_dir][mkdocs.docs_dir] directory.

13 KiB Raw Blame History Unescape Escape